System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 30e827673bcf04cd8d8dac57e3b5b90d666d6148:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 34 22 0a 23 64 65 66 69 6e 65 20 53  .7.14".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 34 0a 23 64 65  MBER 3007014.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 36 2d 32 31 20 31 37 3a 32 31 3a 35 32 20  -06-21 17:21:52 
1080: 64 35 65 36 38 38 30 32 37 39 32 31 30 63 61 36  d5e6880279210ca6
1090: 33 65 32 64 35 65 37 66 36 64 30 30 39 66 33 30  3e2d5e7f6d009f30
10a0: 35 36 36 66 31 32 34 32 22 0a 0a 2f 2a 0a 2a 2a  566f1242"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
55d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
55f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5610: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5630: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5650: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56b0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56d0: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
56e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5700: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5710: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5720: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5730: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5740: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5750: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5760: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5770: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5780: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5790: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
57a0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
57b0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
57c0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
57d0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
57e0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
57f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5800: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5810: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5820: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5830: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5840: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5850: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5870: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
58b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58e0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
58f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5900: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5910: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5940: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5950: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5990: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
59a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59c0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
59d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
59e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5a20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5a50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5a60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5aa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5ab0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ac0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5af0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5b70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5bb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5bf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5c00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5c30: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5c40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c60: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5c70: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5c80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ca0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5cb0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5cc0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5d00: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5d10: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d40: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5d50: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5d60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5da0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5db0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5dc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5df0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e10: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5e30: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5e40: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5e50: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5e60: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5e70: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5e80: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5e90: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5ea0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5eb0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5ec0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5ed0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5ee0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5ef0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5f00: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5f10: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5f20: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5f30: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5f40: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5f50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5f60: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5f70: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5f90: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5fa0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5fb0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5fc0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5fd0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5fe0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5ff0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6000: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6010: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6020: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6030: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6040: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6050: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6060: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6070: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6080: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6090: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
60a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
60b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
60c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
60d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
60e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
60f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6100: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6110: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6120: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6130: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6140: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6150: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6160: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6170: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6180: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6190: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
61a0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
61b0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
61c0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
61d0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
61e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
61f0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6200: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6210: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6220: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6230: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6240: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6260: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6270: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6280: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6290: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
62a0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
62b0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
62c0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
62d0: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
62f0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6300: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6310: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6320: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6330: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6340: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6360: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6370: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6380: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6390: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
63b0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
63c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
63d0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
63e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
63f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6400: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6410: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6420: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6430: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6440: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6450: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6470: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6480: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6490: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
64a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
64b0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
64c0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
64d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
64e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
64f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6500: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6510: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6520: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6530: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6540: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6550: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6560: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6570: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6580: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6590: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
65a0: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
65b0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
65c0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
65d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
65e0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
65f0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6600: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6610: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6620: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6630: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6640: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6650: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6660: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6670: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6680: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6690: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
66a0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
66b0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
66c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
66d0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
66e0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
66f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6700: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6710: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6720: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6730: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6740: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6750: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6760: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6770: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6780: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6790: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
67a0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
67b0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
67c0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
67d0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
67e0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
67f0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6800: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6810: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6820: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6830: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6840: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6850: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6860: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6870: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6880: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6890: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
68a0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
68b0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
68c0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
68d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
68e0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
68f0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6900: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6910: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6920: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6930: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6940: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6950: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6960: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6970: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6980: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6990: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
69a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
69b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
69c0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
69d0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
69e0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
69f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6a00: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6a10: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6a20: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6a30: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6a40: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6a50: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6a60: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6a70: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6a80: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6a90: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6aa0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6ab0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6ac0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6ad0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6ae0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6af0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6b00: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6b10: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6b20: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6b30: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6b40: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6b50: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6b60: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6b70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6b80: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6b90: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6ba0: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6bb0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6bc0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6bd0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6be0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6bf0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6c00: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6c10: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6c20: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6c30: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6c60: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
6c80: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
6c90: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
6ca0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6cb0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
6cc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6cd0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6ce0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6cf0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6d00: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6d10: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6d20: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6d30: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6d40: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6d50: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6d60: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6d70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6d80: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
6d90: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
6da0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
6db0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
6dc0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
6dd0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6de0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6e00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6e20: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6e30: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6e40: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6e50: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6e60: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6e70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6e80: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
6e90: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
6ea0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
6eb0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
6ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
6ed0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6ee0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6ef0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6f00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6f10: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6f20: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6f30: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6f40: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6f50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6f60: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6f70: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
6f80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6f90: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
6fa0: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
6fb0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
6fc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fd0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6fe0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6ff0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7000: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7010: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7020: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7030: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7040: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7050: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7060: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7070: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7080: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7090: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
70a0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
70b0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
70c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
70d0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
70e0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
70f0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7120: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7130: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7140: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7150: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7160: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7170: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7180: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7190: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
71a0: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
71b0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
71c0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
71d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
71e0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
71f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7200: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7210: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7220: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7230: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7240: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7250: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7260: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7270: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7280: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7290: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
72a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
72b0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
72c0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
72d0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
72e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
72f0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7300: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7310: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7320: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7330: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7340: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7350: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7360: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7370: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7380: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7390: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
73a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
73b0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
73c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
73d0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
73f0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7400: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7410: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7420: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7430: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
7440: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
7450: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7460: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
7470: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7480: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7490: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
74a0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
74b0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
74c0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
74d0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
74e0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
74f0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7500: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7510: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7520: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
7530: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
7540: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
7550: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
7560: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
7570: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7580: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7590: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
75a0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
75b0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
75c0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
75d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
75e0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
75f0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7600: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7610: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7620: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7630: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7640: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7650: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7660: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7670: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7680: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7690: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
76a0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
76b0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
76c0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
76d0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
76e0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
76f0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7700: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7710: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7720: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7730: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7740: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7750: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7760: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7770: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7780: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7790: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
77a0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
77b0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
77c0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
77d0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
77e0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
77f0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7800: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7810: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7820: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7830: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7840: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7850: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7860: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7870: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7880: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7890: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
78a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
78b0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
78c0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
78d0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
78e0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
78f0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7900: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7910: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7920: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7930: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7940: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7950: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7960: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7970: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7980: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7990: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
79a0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
79b0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
79c0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
79d0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
79e0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
79f0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7a00: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7a10: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7a20: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7a30: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7a40: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7a50: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7a60: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7a70: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7a80: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7a90: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7aa0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ac0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7ae0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7af0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b00: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b20: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7b30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b40: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b60: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7ba0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7bb0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7bc0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7bd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7be0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7bf0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7c00: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7c10: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7c20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7c30: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7c40: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7c50: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7c60: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7c70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7c80: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7c90: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7ca0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7cb0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7cc0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7cd0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7ce0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7cf0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7d00: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7d10: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7d20: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7d30: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7d40: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7d50: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7d60: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7d70: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7d80: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7d90: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7da0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7db0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7dc0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7dd0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7de0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7df0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7e00: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7e10: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7e20: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7e30: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7e40: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7e50: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7e60: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7e70: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7e80: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7e90: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7ea0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7eb0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7ec0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7ed0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7f00: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7f10: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7f20: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7f30: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7f40: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7f50: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7f60: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7f70: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7f80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7f90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7fa0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7fb0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7fc0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7fd0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7ff0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8010: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8020: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8030: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
8040: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8050: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8060: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8070: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8080: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8090: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
80a0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
80b0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
80c0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
80d0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
80e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
80f0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8100: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8110: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8120: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
8130: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8140: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
8150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8160: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8170: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8180: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8190: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
81a0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
81b0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
81c0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
81d0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
81e0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
81f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8200: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8210: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8220: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8230: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8240: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8250: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8260: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8270: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8280: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8290: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
82a0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
82b0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
82c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
82d0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
82e0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
82f0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8300: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8310: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
8320: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8330: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
8340: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8350: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8360: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
8370: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8380: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8390: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
83a0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
83b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
83c0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
83d0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
83e0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
83f0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
8400: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8410: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8420: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8430: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8440: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8450: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8460: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
8470: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8480: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8490: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
84a0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
84b0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
84c0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
84d0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
84e0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
84f0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8500: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8510: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8520: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8530: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8540: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8550: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8570: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8580: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8590: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
85a0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
85b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
85c0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
85d0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
85e0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
85f0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8600: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8610: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8620: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8630: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8640: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8650: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
8660: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8670: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8680: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8690: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
86a0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
86b0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
86c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
86d0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
86e0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
86f0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8700: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8710: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8720: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8730: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8740: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8750: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
8760: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
8770: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8780: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8790: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
87a0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
87b0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
87c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
87d0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
87e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
87f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8800: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8810: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8820: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8830: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8840: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8850: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
8860: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
8870: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8880: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8890: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
88a0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
88b0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
88c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
88d0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
88e0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
88f0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8900: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8910: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
8920: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
8930: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
8940: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
8950: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
8960: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
8970: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
8980: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
8990: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
89a0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
89b0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
89c0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
89d0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
89e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
89f0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8a00: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
8a10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8a20: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8a30: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8a40: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
8a50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8a60: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
8a70: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
8a80: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
8a90: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
8aa0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8ab0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8ac0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8ad0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8ae0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8af0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b00: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
8b10: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
8b20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8b30: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
8b40: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
8b50: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
8b60: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
8b70: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
8b80: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
8b90: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
8ba0: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
8bc0: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
8bd0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
8be0: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
8bf0: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
8c00: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
8c10: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
8c20: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
8c30: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
8c40: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8c50: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
8c60: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
8c70: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
8c80: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
8c90: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8ca0: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
8cb0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
8cc0: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
8cd0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
8ce0: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
8cf0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d00: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
8d10: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
8d20: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
8d30: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
8d40: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8d50: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
8d60: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
8d70: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8d80: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
8d90: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
8da0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8db0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8dc0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8dd0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
8de0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
8df0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
8e00: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
8e10: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
8e20: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
8e30: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
8e40: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
8e50: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
8e60: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
8e70: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
8e80: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
8e90: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
8ea0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
8eb0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
8ec0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
8ed0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
8ee0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
8ef0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8f00: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8f10: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8f20: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8f30: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8f40: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8f50: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8f60: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8f70: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8f80: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8f90: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
8fa0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
8fb0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
8fc0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8fd0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
8fe0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
8ff0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9000: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9010: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9020: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9030: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9040: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9050: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9060: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9070: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9080: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9090: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
90a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
90b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
90c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
90d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
90e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
90f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9100: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9110: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9120: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9130: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9140: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9150: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9160: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9170: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9180: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9190: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
91a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
91b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
91c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
91e0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
91f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9200: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9210: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9220: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9230: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9240: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9250: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9260: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9270: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9280: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9290: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
92a0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
92b0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
92c0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
92d0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
92e0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
92f0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9300: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9310: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9320: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9330: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9340: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9350: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9360: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9370: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9380: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9390: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
93a0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
93b0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
93c0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
93d0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
93e0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
93f0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9400: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9410: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9420: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9430: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9440: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9450: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9460: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9470: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9480: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9490: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
94a0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
94b0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
94c0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
94d0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
94e0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
94f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9500: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9510: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9520: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9530: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9540: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9550: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9560: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9570: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9580: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9590: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
95a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
95b0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
95c0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
95d0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
95e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
95f0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9600: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9610: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9620: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9630: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9640: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9650: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9660: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9670: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9680: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
9690: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
96a0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
96b0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
96c0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
96d0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
96e0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
96f0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9700: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9710: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9720: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9730: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9740: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9750: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
9760: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9770: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9780: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9790: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
97a0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
97b0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
97c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
97d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97e0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
97f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9800: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9810: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
9820: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
9830: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
9840: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
9850: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
9860: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
9870: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
9880: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
9890: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
98a0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
98b0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
98c0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
98d0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
98e0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
98f0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9910: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
9920: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9930: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
9940: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
9950: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
9960: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
9970: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
9980: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
9990: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
99a0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
99b0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
99c0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
99d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
99e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
99f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9a00: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
9a10: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
9a20: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
9a30: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
9a40: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9a50: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
9a60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
9a70: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
9a80: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
9a90: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
9aa0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
9ab0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
9ac0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
9ad0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
9ae0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
9af0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
9b00: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
9b10: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
9b20: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
9b30: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
9b40: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
9b50: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
9b60: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
9b70: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
9b80: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
9b90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
9ba0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
9bb0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
9bc0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
9bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9be0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
9bf0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
9c00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
9c10: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
9c20: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
9c30: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
9c40: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
9c50: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
9c60: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
9c70: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
9c80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
9c90: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
9ca0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
9cb0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
9cc0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
9cd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9ce0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9cf0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
9d00: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
9d10: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
9d20: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
9d30: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
9d40: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
9d50: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
9d60: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
9d70: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
9d80: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
9d90: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
9da0: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
9db0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
9dc0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
9dd0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
9de0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9df0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
9e00: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
9e10: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
9e20: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
9e30: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
9e40: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
9e50: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
9e60: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
9e70: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
9e80: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
9e90: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
9ea0: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
9eb0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
9ec0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
9ed0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
9ee0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
9ef0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
9f00: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9f10: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
9f20: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
9f30: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
9f40: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
9f50: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
9f60: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9f70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
9f80: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
9f90: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
9fa0: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
9fb0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
9fc0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
9fd0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
9fe0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
9ff0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a000: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a010: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a020: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a030: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a040: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a050: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
a060: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
a070: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a080: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
a090: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
a0a0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
a0b0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a0c0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a0d0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a0e0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a0f0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a100: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a110: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a120: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a130: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a140: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a150: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a160: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a170: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a180: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a190: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a1a0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a1b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
a1c0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
a1d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
a1e0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
a1f0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
a200: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
a210: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
a220: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a230: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
a240: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a250: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
a260: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
a270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a280: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
a290: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
a2a0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
a2b0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
a2c0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
a2d0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
a2e0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
a2f0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
a300: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
a310: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
a320: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
a330: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
a340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a350: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
a360: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
a370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a380: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a390: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
a3a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a3b0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
a3c0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
a3d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a3e0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
a3f0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
a400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a410: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a420: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
a430: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a440: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
a450: 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a          14../*.*
a460: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
a470: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
a480: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
a490: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
a4a0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
a4b0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
a4c0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
a4d0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
a4e0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
a4f0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
a500: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
a510: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
a520: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
a530: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
a540: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
a550: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
a560: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
a570: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
a580: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
a590: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
a5a0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
a5b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a5c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
a5d0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
a5e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a5f0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
a600: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
a610: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
a620: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
a630: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a640: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
a650: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
a660: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
a670: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
a680: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
a690: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
a6a0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
a6b0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
a6c0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
a6d0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
a6e0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
a6f0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
a700: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
a710: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
a720: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
a730: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
a740: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
a750: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
a760: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
a770: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
a780: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
a790: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
a7a0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
a7b0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
a7c0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
a7d0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
a7e0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
a7f0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
a800: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
a810: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
a820: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
a830: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
a840: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
a850: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
a860: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
a870: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
a880: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
a890: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
a8a0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
a8b0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
a8c0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
a8d0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
a8e0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
a8f0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
a900: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
a910: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
a920: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
a930: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
a940: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
a950: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
a960: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
a970: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
a980: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
a990: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
a9a0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
a9b0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
a9c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
a9d0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
a9e0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
a9f0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
aa00: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
aa10: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
aa20: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
aa30: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
aa40: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
aa50: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
aa60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
aa70: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
aa80: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
aa90: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
aaa0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
aab0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
aac0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
aad0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
aae0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
aaf0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
ab00: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
ab10: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
ab20: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
ab30: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
ab40: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
ab50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
ab60: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
ab70: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
ab80: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
ab90: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
aba0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
abb0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
abc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
abd0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
abe0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
abf0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
ac00: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
ac10: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
ac20: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
ac30: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
ac40: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
ac50: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
ac60: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
ac70: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
ac80: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
ac90: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
aca0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
acb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
acc0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
acd0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ace0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
acf0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ad00: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ad10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ad20: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
ad30: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
ad40: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
ad50: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ad60: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
ad70: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
ad80: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
ad90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
ada0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
adb0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
adc0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
add0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
ade0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
adf0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
ae00: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
ae10: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
ae20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ae30: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ae40: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ae50: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ae60: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ae70: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ae80: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ae90: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
aea0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
aeb0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
aec0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
aed0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
aee0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
aef0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
af00: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
af10: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
af20: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
af30: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
af40: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
af50: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
af60: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
af70: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
af80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
af90: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
afa0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
afb0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
afc0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
afd0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
afe0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
aff0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
b000: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
b010: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
b020: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
b030: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
b040: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
b050: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
b060: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
b070: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
b080: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
b090: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
b0a0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
b0b0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
b0c0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
b0d0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
b0e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
b0f0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
b100: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
b110: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
b120: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
b130: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
b140: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
b150: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
b160: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
b170: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
b180: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
b190: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
b1a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b1b0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
b1c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b1d0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
b1e0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b1f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
b200: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b210: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
b220: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b230: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
b240: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
b250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
b260: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
b270: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b280: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
b290: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b2a0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
b2b0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
b2c0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
b2d0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
b2e0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
b2f0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
b300: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
b310: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
b320: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
b330: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
b340: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
b350: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
b360: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
b370: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
b380: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
b390: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
b3a0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
b3b0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
b3c0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
b3d0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
b3e0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
b3f0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
b400: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
b410: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
b420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
b430: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
b440: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
b450: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
b460: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
b470: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
b480: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
b490: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
b4a0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
b4b0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
b4c0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
b4d0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
b4e0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b4f0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b500: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
b510: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
b520: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b530: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b540: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
b550: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b560: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
b570: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
b580: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
b590: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
b5a0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
b5b0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
b5c0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
b5d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
b5e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b5f0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
b600: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
b610: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
b620: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
b630: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
b640: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
b650: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
b660: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
b670: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
b680: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
b690: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
b6a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
b6b0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
b6c0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
b6d0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
b6e0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
b6f0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
b700: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
b710: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
b720: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
b730: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
b740: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
b750: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
b760: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
b770: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
b780: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
b790: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
b7a0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
b7b0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
b7c0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
b7d0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
b7e0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
b7f0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
b800: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
b810: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
b820: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
b830: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
b840: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
b850: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
b860: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
b870: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
b880: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
b890: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
b8a0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
b8b0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
b8c0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
b8d0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
b8e0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
b8f0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
b900: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
b910: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
b920: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
b930: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
b940: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b950: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
b960: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
b970: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
b980: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
b990: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
b9a0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
b9b0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
b9c0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
b9d0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
b9e0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
b9f0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
ba00: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
ba10: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
ba20: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
ba30: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
ba40: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
ba50: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
ba60: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
ba70: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
ba80: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
ba90: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
baa0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
bab0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
bac0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
bad0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
bae0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
baf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
bb00: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
bb10: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
bb20: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
bb30: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
bb40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
bb50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
bb60: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
bb70: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
bb80: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
bb90: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
bba0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
bbb0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
bbc0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
bbd0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
bbe0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
bbf0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
bc00: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
bc10: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
bc20: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
bc30: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
bc40: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
bc50: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
bc60: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
bc70: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
bc80: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
bc90: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
bca0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
bcb0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
bcc0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
bcd0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
bce0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
bcf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bd00: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
bd10: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
bd20: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
bd30: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
bd40: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
bd50: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
bd60: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
bd70: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
bd80: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
bd90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bda0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
bdb0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
bdc0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
bdd0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
bde0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
bdf0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
be00: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
be10: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
be20: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
be30: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
be40: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
be50: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
be60: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
be70: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
be80: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
be90: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
bea0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
beb0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
bec0: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
bed0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
bee0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
bef0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
bf00: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
bf10: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
bf20: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
bf30: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
bf40: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
bf50: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
bf60: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
bf70: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
bf80: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
bf90: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
bfa0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
bfb0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
bfc0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
bfd0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
bfe0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
bff0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
c000: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
c010: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
c020: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
c030: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
c040: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
c050: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
c060: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
c070: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
c080: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
c090: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
c0a0: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
c0b0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
c0c0: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
c0d0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
c0e0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
c0f0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
c100: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
c110: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
c120: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
c130: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
c140: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
c150: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
c160: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
c170: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
c180: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
c190: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
c1a0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
c1b0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
c1c0: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
c1d0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
c1e0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
c1f0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
c200: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
c210: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
c220: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
c230: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
c240: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
c250: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
c260: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
c270: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
c280: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
c290: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
c2a0: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
c2b0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
c2c0: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
c2d0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
c2e0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
c2f0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
c300: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
c310: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
c320: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
c330: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
c340: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
c350: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
c360: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
c370: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
c380: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
c390: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
c3a0: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
c3b0: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
c3c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
c3d0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
c3e0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
c3f0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
c400: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
c410: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
c420: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
c430: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
c440: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
c450: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
c460: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
c470: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
c480: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
c490: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
c4a0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
c4b0: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
c4c0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
c4d0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
c4e0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
c4f0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
c500: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
c510: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
c520: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
c530: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
c540: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
c550: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
c560: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
c570: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
c580: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
c590: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
c5a0: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
c5b0: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
c5c0: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
c5d0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
c5e0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
c5f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
c600: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
c610: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
c620: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
c630: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
c640: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
c650: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
c660: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
c670: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
c680: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
c690: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c6a0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
c6b0: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
c6c0: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
c6d0: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
c6e0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
c6f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c700: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c710: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
c720: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
c730: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c740: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c750: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c760: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c770: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
c780: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c790: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c7a0: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
c7b0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
c7c0: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
c7d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c7e0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
c7f0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
c800: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
c810: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
c820: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
c830: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
c840: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
c850: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
c860: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
c870: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
c880: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
c890: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
c8a0: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
c8b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
c8c0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
c8d0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
c8e0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
c8f0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
c900: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
c910: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
c920: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
c930: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
c940: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
c950: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
c960: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
c970: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
c980: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
c990: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
c9a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
c9b0: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
c9c0: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
c9d0: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
c9e0: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
c9f0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
ca00: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ca10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ca20: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
ca30: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ca40: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ca50: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
ca60: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
ca70: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ca80: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
ca90: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
caa0: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
cab0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
cac0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
cad0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
cae0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
caf0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
cb00: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
cb10: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
cb20: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
cb30: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
cb40: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
cb50: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
cb60: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
cb70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
cb80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
cb90: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
cba0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
cbb0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
cbc0: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
cbd0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cbe0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
cbf0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cc00: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
cc10: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
cc20: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
cc30: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
cc40: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
cc50: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
cc60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
cc70: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
cc80: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
cc90: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
cca0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
ccb0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
ccc0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
ccd0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
cce0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
ccf0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
cd00: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
cd10: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
cd20: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
cd30: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
cd40: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
cd50: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
cd60: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
cd70: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
cd80: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
cd90: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
cda0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
cdb0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
cdc0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
cdd0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cde0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cdf0: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
ce00: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
ce10: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
ce20: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
ce30: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
ce40: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
ce50: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
ce60: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
ce70: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
ce80: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
ce90: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
cea0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
ceb0: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
cec0: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
ced0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
cee0: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
cef0: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
cf00: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
cf10: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
cf20: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
cf30: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
cf40: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cf50: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
cf60: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
cf70: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
cf80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
cf90: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
cfa0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
cfb0: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
cfc0: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
cfd0: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
cfe0: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
cff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d000: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
d010: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
d020: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d030: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
d040: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
d050: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
d060: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d070: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
d080: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
d090: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
d0a0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d0b0: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
d0c0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
d0d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
d0e0: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
d0f0: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
d100: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
d110: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
d120: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
d130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d140: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
d150: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
d160: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
d170: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
d180: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
d190: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
d1a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
d1b0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d1c0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
d1d0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
d1e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
d1f0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
d200: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
d210: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
d220: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d230: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
d240: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
d250: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
d260: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
d270: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
d280: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
d290: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
d2a0: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
d2b0: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
d2c0: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72  given no the cor
d2d0: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
d2e0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
d2f0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
d300: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
d310: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d320: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
d330: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
d340: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
d350: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
d360: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
d370: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
d380: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
d390: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
d3a0: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
d3b0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
d3c0: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
d3d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
d3e0: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
d3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
d400: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
d410: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d420: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
d430: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
d440: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
d450: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
d460: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
d470: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
d480: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
d490: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
d4a0: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
d4b0: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
d4c0: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
d4d0: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
d4e0: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
d4f0: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
d500: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
d510: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d520: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
d530: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
d540: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
d550: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
d560: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
d570: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d580: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
d590: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
d5a0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
d5b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
d5c0: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
d5d0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
d5e0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
d5f0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
d600: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
d610: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
d620: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
d630: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
d640: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
d650: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
d660: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
d670: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
d680: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
d690: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
d6a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
d6b0: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
d6c0: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
d6d0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
d6e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
d6f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
d700: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
d710: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
d720: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
d730: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
d740: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d750: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
d760: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
d770: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
d780: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
d790: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
d7a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d7b0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
d7c0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
d7d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
d7e0: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
d7f0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
d800: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
d810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
d820: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
d830: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
d840: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
d850: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d860: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
d870: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d880: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
d890: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
d8a0: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
d8b0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d8c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
d8d0: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
d8e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
d8f0: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
d900: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
d910: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d920: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
d930: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
d940: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
d950: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
d960: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
d970: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
d980: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
d990: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d9a0: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
d9b0: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
d9c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d9d0: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
d9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
d9f0: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
da00: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
da10: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
da20: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
da30: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
da40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
da50: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
da60: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
da70: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
da80: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
da90: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
daa0: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
dab0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
dac0: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
dad0: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
dae0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
daf0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
db00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
db10: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
db20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
db30: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
db40: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
db50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
db60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
db70: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
db80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
db90: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
dba0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
dbb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dbc0: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
dbd0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
dbe0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
dbf0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
dc00: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
dc10: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
dc20: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
dc30: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
dc40: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
dc50: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
dc60: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
dc70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
dc80: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
dc90: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
dca0: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
dcb0: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
dcc0: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
dcd0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
dce0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
dcf0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
dd00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dd10: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
dd20: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
dd30: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
dd40: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
dd50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
dd60: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
dd70: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
dd80: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
dd90: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
dda0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
ddb0: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
ddc0: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
ddd0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
dde0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
ddf0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
de00: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
de10: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
de20: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
de30: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
de40: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
de50: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
de60: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
de70: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
de80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
de90: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
dea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
deb0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
dec0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
ded0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
dee0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
def0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
df00: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
df10: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
df20: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
df30: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
df40: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
df50: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
df60: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
df70: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
df80: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
df90: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
dfa0: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
dfb0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
dfc0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
dfd0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
dfe0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
dff0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
e000: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
e010: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
e020: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
e030: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
e040: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
e050: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
e060: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e070: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
e080: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
e090: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
e0a0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
e0b0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
e0c0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
e0d0: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
e0e0: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
e0f0: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
e100: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
e110: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
e120: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
e130: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
e140: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
e150: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
e160: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
e170: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
e180: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
e190: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
e1a0: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
e1c0: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
e1d0: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
e1e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
e1f0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
e200: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
e210: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
e220: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
e230: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
e240: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
e250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e260: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
e270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e280: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
e290: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
e2a0: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
e2b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e2c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
e2d0: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
e2e0: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
e2f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
e300: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e310: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
e320: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
e330: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
e340: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
e350: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
e360: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
e370: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e380: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
e390: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
e3a0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
e3b0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
e3c0: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
e3d0: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
e3e0: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
e3f0: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
e400: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
e410: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
e420: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
e430: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
e440: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
e450: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
e460: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
e470: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
e480: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
e490: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
e4a0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
e4b0: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
e4c0: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
e4d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
e4e0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
e4f0: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
e500: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
e510: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
e520: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
e530: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
e540: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
e550: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51  * failure..*/.SQ
e560: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
e570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e580: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
e590: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  I int sqlite3_sh
e5a0: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51  utdown(void);.SQ
e5b0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
e5c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e5d0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
e5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
e5f0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
e600: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e610: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
e620: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
e630: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
e640: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
e650: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
e660: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
e670: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e680: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
e690: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
e6a0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
e6b0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
e6c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
e6d0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
e6e0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
e6f0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
e700: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
e710: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
e720: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
e730: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
e740: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
e750: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
e760: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
e770: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
e780: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
e790: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
e7a0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
e7b0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
e7c0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
e7d0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
e7e0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
e7f0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
e800: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
e810: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
e820: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e830: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
e840: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
e850: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
e860: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
e870: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
e880: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
e890: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
e8a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e8b0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
e8c0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
e8d0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
e8e0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
e8f0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
e900: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
e910: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
e920: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
e930: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e940: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
e950: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
e960: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
e970: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
e980: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
e990: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
e9a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
e9b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
e9c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e9d0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
e9e0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
e9f0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
ea00: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
ea10: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
ea20: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
ea30: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
ea40: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ea50: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ea60: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ea70: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ea80: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
ea90: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
eaa0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
eab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
eac0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ead0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
eae0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
eaf0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
eb00: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
eb10: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
eb20: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
eb30: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
eb40: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
eb50: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
eb60: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
eb70: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
eb80: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
eb90: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
eba0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
ebb0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
ebc0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
ebd0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
ebe0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
ebf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ec00: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
ec10: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ec20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
ec30: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
ec40: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
ec50: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
ec60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ec70: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
ec80: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
ec90: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
eca0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ecb0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ecc0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
ecd0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ece0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
ecf0: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
ed00: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
ed10: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
ed20: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ed30: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
ed40: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
ed50: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
ed60: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
ed70: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
ed80: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
ed90: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
eda0: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
edb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
edc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
edd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
ede0: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
edf0: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
ee00: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ee10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
ee20: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
ee30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
ee40: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
ee50: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
ee60: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
ee70: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
ee80: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
ee90: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eea0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
eeb0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
eec0: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
eed0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
eee0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
eef0: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
ef00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ef10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ef20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
ef30: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
ef40: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
ef50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ef60: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
ef70: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
ef80: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
ef90: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
efa0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
efb0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
efc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
efd0: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
efe0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
eff0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f000: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
f010: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f020: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
f030: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
f040: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
f050: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
f060: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
f070: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
f080: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
f090: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
f0a0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
f0b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f0c0: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
f0d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
f0e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
f0f0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f100: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f110: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
f120: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
f130: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
f140: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
f150: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
f160: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
f170: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
f180: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
f190: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
f1a0: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
f1b0: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
f1c0: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
f1d0: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
f1e0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
f1f0: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
f200: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
f210: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
f220: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
f230: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
f240: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
f250: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
f260: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
f270: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
f280: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
f290: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
f2a0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
f2b0: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
f2c0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
f2d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f2e0: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
f2f0: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
f300: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
f310: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
f320: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
f330: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
f340: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
f350: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
f360: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
f370: 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
f380: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
f390: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
f3a0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
f3b0: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
f3c0: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
f3d0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
f3e0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
f3f0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
f400: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
f410: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
f420: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
f430: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
f440: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
f450: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
f460: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
f470: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
f480: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
f490: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f4a0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
f4b0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
f4c0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
f4d0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
f4e0: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
f4f0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
f500: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
f510: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
f520: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
f530: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
f540: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
f550: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
f560: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
f570: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
f580: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
f590: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
f5a0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
f5b0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
f5c0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f5d0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
f5e0: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
f5f0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
f600: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
f610: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
f620: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
f630: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
f640: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
f650: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
f660: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
f670: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
f680: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
f690: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
f6a0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
f6b0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
f6c0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
f6d0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
f6e0: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
f6f0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f700: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f710: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
f720: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
f730: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
f740: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f750: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
f760: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
f770: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
f780: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
f790: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
f7a0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
f7b0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
f7c0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
f7d0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
f7e0: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
f7f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
f800: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
f810: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
f820: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
f830: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
f840: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
f850: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
f860: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
f870: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
f880: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
f890: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
f8a0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
f8b0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
f8c0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
f8d0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
f8e0: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
f8f0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
f900: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
f910: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
f920: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
f930: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
f940: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
f950: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
f960: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
f970: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
f980: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
f990: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
f9a0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
f9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
f9c0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
f9d0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
f9e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
f9f0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
fa00: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fa10: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
fa20: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
fa30: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
fa40: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
fa50: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
fa60: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
fa70: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
fa80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
fa90: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
faa0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
fab0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
fac0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
fad0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
fae0: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
faf0: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
fb00: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
fb10: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
fb20: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
fb30: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
fb40: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
fb50: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
fb60: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
fb70: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
fb80: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
fb90: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
fba0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
fbb0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
fbc0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
fbd0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
fbe0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
fbf0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
fc00: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
fc10: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
fc20: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
fc30: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
fc40: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
fc50: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
fc60: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
fc70: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
fc80: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
fc90: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
fca0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
fcb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
fcc0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
fcd0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
fce0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
fcf0: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
fd00: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
fd10: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
fd20: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
fd30: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
fd40: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
fd60: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
fd70: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
fd80: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
fd90: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
fda0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
fdb0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
fdc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
fdd0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
fde0: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
fdf0: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
fe00: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fe10: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
fe20: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
fe30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fe40: 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
fe50: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
fe60: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
fe70: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
fe80: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
fe90: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
fea0: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
feb0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
fec0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fed0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
fee0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
fef0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
ff00: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
ff10: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
ff20: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
ff30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
ff40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
ff50: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
ff60: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
ff70: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
ff80: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
ff90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
ffa0: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
ffb0: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
ffc0: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
ffd0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ffe0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
fff0: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
10000 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10010 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
10020 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
10030 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
10040 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10050 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10060 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
10070 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
10080 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
10090 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
100a0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
100b0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
100c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
100d0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
100e0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
100f0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10100 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
10110 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
10120 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
10130 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
10140 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
10150 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
10160 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
10170 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
10180 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
10190 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
101a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
101b0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
101c0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
101d0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
101e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
101f0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
10200 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
10210 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
10220 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
10230 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
10240 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
10250 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
10260 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10270 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
10280 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
10290 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
102a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
102b0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
102c0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
102d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
102e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
102f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
10300 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10310 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
10320 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
10330 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
10340 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10350 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
10360 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
10370 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
10380 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
10390 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
103a0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
103b0 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
103c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
103d0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
103e0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
103f0 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
10400 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
10410 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
10420 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
10430 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10440 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
10450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10460 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
10470 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
10480 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
10490 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
104a0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
104b0 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
104c0 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
104d0 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
104e0 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
104f0 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
10500 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10510 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
10520 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
10530 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10540 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10550 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10560 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10570 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
10580 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
10590 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
105a0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
105b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
105c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
105d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
105e0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
105f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
10600 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
10610 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
10620 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
10630 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
10640 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
10650 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10660 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
10670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10680 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
10690 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
106a0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
106b0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
106c0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
106d0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
106e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
106f0 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
10700 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
10710 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
10720 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
10730 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
10740 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
10750 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
10760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
10770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10780 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
10790 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
107a0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
107b0 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
107c0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
107d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
107e0 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
107f0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
10800 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
10810 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
10820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10830 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
10840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
10850 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
10860 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
10870 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
10880 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
10890 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
108a0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
108b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
108c0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
108d0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
108e0 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
108f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10900 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10910 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10930 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10940 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10950 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10960 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
10970 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
10980 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10990 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
109a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
109b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
109c0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
109d0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
109e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
109f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10a00 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10a10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10a20 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
10a30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10a40 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
10a50 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
10a60 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
10a70 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10a80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10a90 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
10ab0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10ac0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
10ad0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
10ae0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
10af0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10b00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
10b10 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
10b20 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
10b30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
10b40 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
10b50 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
10b60 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
10b70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
10b80 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
10b90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10ba0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10bb0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
10bc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
10bd0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
10be0 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
10bf0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10c00 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
10c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10c20 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
10c30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10c40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10c50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10c60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10c70 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
10c80 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
10c90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
10ca0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
10cb0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10cc0 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
10cd0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
10ce0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
10cf0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
10d00 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10d10 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
10d20 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
10d30 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
10d40 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
10d50 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10d60 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10d70 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
10d80 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
10d90 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
10da0 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
10db0 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
10dc0 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
10dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10de0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
10df0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10e00 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
10e10 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
10e20 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
10e30 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
10e40 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
10e50 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
10e60 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
10e70 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
10e80 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
10e90 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
10ea0 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
10eb0 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
10ec0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
10ed0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
10ee0 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66  abled, the .** f
10ef0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
10f00 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
10f10 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
10f20 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
10f30 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10f40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
10f50 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
10f60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
10f70 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
10f80 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
10f90 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
10fa0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10fb0 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
10fc0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
10fd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
10fe0 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
10ff0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
11000 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
11010 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
11020 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
11030 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
11040 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
11050 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
11060 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
11070 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
11080 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
11090 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
110a0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
110b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
110c0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
110d0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
110e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
110f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
11100 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
11110 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
11120 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
11130 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
11140 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
11150 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
11160 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
11170 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
11180 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
11190 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
111a0 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
111b0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
111c0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
111d0 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
111e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
111f0 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
11200 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
11210 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
11220 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
11230 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
11240 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11250 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
11260 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
11270 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
11280 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
11290 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
112a0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
112b0 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
112c0 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
112d0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
112e0 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
112f0 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
11300 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
11310 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
11320 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
11330 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
11340 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
11350 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
11360 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
11370 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
11380 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
11390 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
113a0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
113b0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
113c0 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
113d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
113e0 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
113f0 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
11400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
11410 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
11420 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
11430 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
11440 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11460 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
11470 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11480 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
11490 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
114a0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
114b0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
114c0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
114d0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
114e0 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
114f0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
11500 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
11510 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
11520 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
11530 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
11540 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
11550 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11560 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
11570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11580 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
11590 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
115a0 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
115b0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
115c0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
115d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
115e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
115f0 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
11600 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
11610 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
11620 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
11630 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
11640 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
11650 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
11660 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
11670 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
11680 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
11690 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
116a0 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
116b0 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
116c0 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
116d0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
116e0 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
116f0 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
11700 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
11710 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
11720 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
11730 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
11740 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
11750 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
11760 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
11770 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
11780 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
11790 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
117a0 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
117b0 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
117c0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
117d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
117e0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
117f0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
11800 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
11810 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
11820 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
11830 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
11840 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
11850 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
11860 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
11870 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
11880 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
11890 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
118a0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
118b0 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
118c0 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
118d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
118e0 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
118f0 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
11900 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
11910 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
11920 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
11930 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
11940 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
11950 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
11960 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
11970 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
11980 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
11990 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
119a0 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
119b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
119c0 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
119d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
119e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
119f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
11a00 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
11a10 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
11a20 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
11a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a40 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
11a50 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
11a60 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
11a70 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
11a80 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
11a90 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
11aa0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
11ab0 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
11ac0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
11ad0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
11ae0 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
11af0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
11b00 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
11b10 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
11b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11b30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
11b40 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
11b50 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
11b60 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
11b70 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
11b80 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
11b90 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
11ba0 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
11bb0 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
11bc0 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
11bd0 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
11be0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
11bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11c00 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
11c10 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
11c20 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
11c30 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
11c40 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
11c50 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
11c60 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
11c70 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
11c80 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
11c90 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11ca0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
11cb0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
11cc0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
11cd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
11ce0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
11cf0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11d00 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
11d10 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
11d20 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
11d30 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
11d40 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
11d50 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
11d60 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
11d70 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
11d80 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
11d90 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
11da0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
11db0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
11dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11dd0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
11de0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
11df0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11e00 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
11e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
11e20 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
11e30 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11e40 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11e50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
11e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
11e70 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
11e80 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
11e90 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11ea0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11eb0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11ec0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11ed0 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
11ee0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
11ef0 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
11f00 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
11f10 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11f20 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
11f30 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
11f40 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
11f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
11f60 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
11f70 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
11f80 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
11f90 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
11fa0 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
11fb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11fc0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11fd0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11fe0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11ff0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12000 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12010 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
12020 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
12030 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
12040 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
12050 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
12060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12070 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
12080 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
12090 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
120a0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
120b0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
120c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
120d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
120e0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
120f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12100 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
12110 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12120 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12130 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12140 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12150 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12160 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
12170 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12180 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
12190 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
121a0 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
121b0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
121c0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
121d0 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
121e0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
121f0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
12200 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
12210 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
12220 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
12230 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12240 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
12250 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
12260 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
12270 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
12280 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
12290 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
122a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
122b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
122c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
122d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
122e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
122f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12300 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12310 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12320 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12330 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12340 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12360 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12370 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
12380 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
12390 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
123a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
123b0 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
123e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
123f0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
12400 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12410 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
12420 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
12430 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
12440 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
12450 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
12460 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
12470 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
12480 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
12490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
124a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
124b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
124c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
124d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
124e0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
124f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
12500 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
12510 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
12520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
12530 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
12540 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
12550 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
12560 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
12570 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
12580 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
12590 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
125a0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
125b0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
125c0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
125d0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
125e0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
125f0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
12600 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12610 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12620 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
12630 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
12640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12650 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12660 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12670 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12680 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
12690 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
126a0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
126b0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
126c0 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
126d0 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
126e0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
126f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
12700 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
12710 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
12720 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
12730 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
12740 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12750 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
12760 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12770 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
12780 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12790 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
127a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
127b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
127c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
127d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
127e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
127f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
12800 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
12810 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
12820 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
12830 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
12840 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
12850 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
12860 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12870 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
12880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12890 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
128a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
128b0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
128c0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
128d0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
128e0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
128f0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
12900 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
12910 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
12920 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
12930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
12940 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
12950 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
12960 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
12970 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
12980 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
12990 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
129a0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
129b0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
129c0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
129d0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
129e0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
129f0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
12a00 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
12a10 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
12a20 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12a30 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
12a40 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
12a50 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
12a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12a70 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
12a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
12a90 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
12aa0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
12ab0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
12ac0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
12ad0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12ae0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
12af0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
12b00 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
12b10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
12b20 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
12b30 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
12b40 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
12b50 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
12b60 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
12b70 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
12b80 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
12b90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
12ba0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
12bb0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
12bc0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
12bd0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
12be0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
12bf0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
12c00 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
12c10 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
12c20 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
12c30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
12c40 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
12c50 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
12c60 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
12c70 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
12c80 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
12c90 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
12ca0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12cb0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
12cc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
12cd0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
12ce0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
12d00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12d10 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20  FIG_URI.** <dd> 
12d20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12d30 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12d40 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
12d50 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
12d60 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69  en.** URI handli
12d70 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
12d80 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
12d90 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
12da0 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
12db0 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c  ing.** is global
12dc0 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20  ly disabled. If 
12dd0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12de0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
12df0 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
12e00 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
12e10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
12e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
12e30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
12e40 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
12e50 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
12e60 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
12e70 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
12e80 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
12e90 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
12ea0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
12eb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
12ec0 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
12ed0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
12ee0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
12ef0 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20  s opened. If it 
12f00 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
12f10 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
12f20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
12f30 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
12f40 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
12f50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
12f60 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
12f70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12f80 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79  on is opened. By
12f90 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
12fa0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12fb0 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
12fc0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
12fd0 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
12fe0 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
12ff0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
13000 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
13010 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
13020 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13030 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13050 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13070 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
13080 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
13090 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
130a0 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
130b0 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
130c0 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
130d0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
130e0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
130f0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
13100 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
13110 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
13120 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
13130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13140 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
13150 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
13160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13170 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
13180 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
131a0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
131b0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
131c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
131d0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
131e0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
131f0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
13200 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13210 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
13220 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
13230 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13240 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13250 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
13260 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
13270 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
13280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13290 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
132a0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
132b0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
132c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
132d0 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
132e0 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
132f0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
13300 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
13310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13320 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
13330 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
13340 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13350 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
13360 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
13370 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
13380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13390 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
133a0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
133b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
133c0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
133d0 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
133e0 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
133f0 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
13400 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13420 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
13430 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
13440 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13450 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
13460 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
13470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13480 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
13490 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
134a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
134b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
134c0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
134d0 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
134e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
134f0 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
13500 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
13510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13520 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
13530 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
13540 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
13550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13570 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
13580 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13590 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  hods2* */../*.**
135a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
135b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
135c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
135d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
135e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
135f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
13600 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
13610 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
13620 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
13630 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
13640 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
13650 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13660 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
13670 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
13680 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13690 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
136a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
136b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
136c0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
136d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
136e0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
136f0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
13700 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
13710 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
13720 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
13730 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
13740 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
13750 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
13760 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
13770 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
13780 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13790 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
137a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
137b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
137c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
137d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
137f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13800 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13810 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13830 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13840 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
13850 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
13860 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
13870 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
13880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
13890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
138a0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
138b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
138c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
138d0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
138e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
138f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13900 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
13910 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
13920 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
13930 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13940 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
13950 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
13960 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
13970 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
13980 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
13990 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
139a0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
139b0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
139c0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
139d0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
139e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
139f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13a00 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13a10 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13a20 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
13a30 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
13a40 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
13a50 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
13a60 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
13a70 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
13a80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13a90 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
13aa0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
13ab0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
13ac0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
13ad0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
13ae0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
13af0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
13b00 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
13b10 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
13b20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13b30 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
13b40 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
13b50 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
13b60 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
13b70 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
13b80 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
13b90 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
13ba0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
13bb0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
13bc0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
13bd0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
13be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
13bf0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
13c00 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
13c10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
13c20 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
13c30 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
13c40 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
13c50 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
13c60 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
13c70 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
13c80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
13c90 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
13ca0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13cb0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
13cc0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
13cd0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13ce0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
13cf0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
13d00 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
13d10 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
13d20 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
13d30 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
13d40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
13d50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
13d60 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
13d70 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
13d80 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
13d90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
13da0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13db0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
13dc0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
13dd0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
13de0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
13df0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
13e00 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
13e10 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
13e20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13e30 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
13e40 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
13e50 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
13e60 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
13e70 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
13e80 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
13e90 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
13ea0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
13eb0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
13ec0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
13ed0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
13ee0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
13ef0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
13f00 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
13f10 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
13f20 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
13f30 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
13f40 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
13f50 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
13f60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13f70 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
13f80 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
13f90 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
13fa0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
13fb0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
13fc0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
13fd0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
13fe0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
13ff0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
14000 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
14010 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
14020 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
14030 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
14040 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
14050 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
14060 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
14070 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
14080 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
14090 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
140a0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
140b0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
140c0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
140d0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
140e0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
140f0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
14100 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
14110 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14130 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
14140 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
14150 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
14160 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
14170 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
14180 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
14190 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
141a0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
141b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
141c0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
141d0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
141e0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
141f0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
14200 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
14210 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
14220 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
14230 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14240 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
14250 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
14260 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
14270 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
14280 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
14290 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
142a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
142b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
142c0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
142d0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
142e0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
142f0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
14300 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
14310 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
14320 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
14330 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14340 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
14350 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14360 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
14370 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
14380 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
14390 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
143a0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
143b0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
143c0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
143d0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
143e0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
143f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
14400 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
14410 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
14420 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
14430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
14440 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
14450 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
14460 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
14470 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
14480 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
14490 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
144a0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
144b0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
144c0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
144d0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
144e0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
144f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
14500 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
14510 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
14520 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
14530 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
14540 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
14550 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
14560 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
14570 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
14580 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
14590 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
145a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
145b0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
145c0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
145d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
145e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
145f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
14600 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
14610 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14620 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
14630 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
14640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14650 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
14660 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
14670 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
14680 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
14690 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
146a0 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
146b0 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
146c0 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
146d0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
146e0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
146f0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
14700 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
14710 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
14720 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
14730 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
14740 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
14750 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
14760 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
14770 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
14780 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
14790 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
147a0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
147b0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
147c0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
147d0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
147e0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
147f0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
14800 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
14810 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
14820 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
14830 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14840 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
14850 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
14860 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
14870 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
14880 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
14890 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
148a0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
148b0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
148c0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
148d0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
148e0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
148f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
14900 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
14910 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
14920 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
14930 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
14940 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
14950 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
14960 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
14970 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
14980 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
14990 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
149a0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
149b0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
149c0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
149d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
149e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
149f0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
14a00 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
14a10 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
14a20 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
14a30 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
14a40 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
14a50 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
14a60 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
14a70 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
14a80 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
14a90 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
14aa0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
14ab0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
14ac0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
14ad0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
14ae0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
14af0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
14b00 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
14b10 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
14b20 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
14b30 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
14b40 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
14b50 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
14b60 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
14b70 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
14b80 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
14b90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
14ba0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
14bb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
14bc0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
14bd0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
14be0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
14bf0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
14c00 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
14c10 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
14c20 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
14c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14c40 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
14c50 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
14c60 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
14c70 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
14c80 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
14c90 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
14ca0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
14cb0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
14cc0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
14cd0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
14ce0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
14cf0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
14d00 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
14d10 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
14d20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
14d30 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
14d40 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
14d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
14d60 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
14d70 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
14d80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14d90 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
14da0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
14db0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
14dc0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
14dd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
14de0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
14df0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
14e00 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
14e10 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
14e20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
14e30 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
14e40 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
14e50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
14e60 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
14e70 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
14e80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
14e90 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
14ea0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
14eb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
14ec0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
14ed0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
14ee0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
14ef0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
14f00 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
14f10 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
14f20 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
14f30 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
14f40 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
14f50 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
14f60 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14f70 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
14f80 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
14f90 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
14fa0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
14fb0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
14fc0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
14fd0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
14ff0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
15000 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
15010 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
15020 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
15030 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
15040 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
15050 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
15060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
15070 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
15080 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
15090 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
150a0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
150b0 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
150c0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
150d0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
150e0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
150f0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
15100 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
15110 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
15120 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
15130 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
15140 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
15150 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
15160 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
15170 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
15180 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
15190 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
151a0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
151b0 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
151c0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
151d0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
151e0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
151f0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
15200 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
15210 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
15220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15230 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
15240 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
15250 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
15260 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
15270 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
15280 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
15290 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
152a0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
152b0 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
152c0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
152d0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
152e0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
152f0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
15300 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
15310 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
15320 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
15330 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
15340 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
15350 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15360 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
15370 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
15380 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
15390 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
153a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
153b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
153c0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
153d0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
153e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
153f0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
15400 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
15410 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
15420 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
15430 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
15440 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
15450 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
15460 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
15470 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
15480 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
15490 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
154a0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
154b0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
154c0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
154d0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
154e0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
154f0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
15500 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
15510 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
15520 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
15530 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
15540 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15550 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
15560 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
15570 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
15580 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
15590 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
155a0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
155b0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
155c0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
155d0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
155e0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
155f0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
15600 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
15610 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
15620 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
15630 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
15640 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
15650 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15660 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
15670 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
15680 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
15690 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
156a0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
156b0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
156c0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
156d0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
156e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
156f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15700 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
15710 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
15720 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
15730 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
15740 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
15750 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
15760 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
15770 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
15780 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
15790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
157a0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
157b0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
157c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
157d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
157e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
157f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
15800 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
15810 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
15820 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
15830 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
15840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
15850 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
15860 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
15870 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
15880 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
15890 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
158a0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
158b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
158c0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
158d0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
158e0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
158f0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
15900 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
15910 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
15920 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
15930 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
15940 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
15950 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
15960 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
15970 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
15980 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
15990 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
159a0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
159b0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
159c0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
159d0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
159e0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
159f0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
15a00 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
15a10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
15a20 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
15a30 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
15a40 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
15a50 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
15a60 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
15a70 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
15a80 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
15a90 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
15aa0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
15ab0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
15ac0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
15ad0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
15ae0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
15af0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
15b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
15b10 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
15b20 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
15b30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
15b40 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
15b50 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
15b60 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
15b70 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
15b80 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
15b90 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
15ba0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
15bb0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
15bc0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
15bd0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
15be0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
15bf0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
15c00 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
15c10 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
15c20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
15c30 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
15c40 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
15c50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
15c60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
15c70 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15c80 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
15c90 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
15ca0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
15cb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
15cc0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
15cd0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
15ce0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
15cf0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
15d00 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
15d10 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
15d20 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
15d30 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
15d40 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
15d50 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
15d60 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
15d70 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
15d80 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
15d90 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
15da0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
15db0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
15dc0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
15dd0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
15de0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
15df0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
15e00 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
15e10 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
15e20 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
15e30 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
15e40 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
15e50 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
15e60 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
15e70 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
15e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15e90 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
15ea0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
15eb0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
15ec0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
15ed0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
15ee0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
15ef0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
15f00 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
15f10 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
15f20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
15f30 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
15f40 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
15f50 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
15f60 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
15f70 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
15f80 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
15f90 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
15fa0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
15fb0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
15fc0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
15fd0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
15fe0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
15ff0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
16000 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
16010 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16020 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
16030 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
16040 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
16050 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
16060 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
16070 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
16080 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
16090 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
160a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
160b0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
160c0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
160d0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
160e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
160f0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
16100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
16110 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
16120 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
16130 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16140 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16150 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16160 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
16170 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
16180 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
16190 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
161a0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
161b0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
161c0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
161d0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
161e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
161f0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
16200 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
16210 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
16220 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
16230 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
16240 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
16250 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
16260 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
16270 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
16280 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
16290 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
162a0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
162b0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
162c0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
162d0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
162e0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
162f0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
16300 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
16310 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
16320 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
16330 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
16340 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
16350 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16360 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
16370 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
16380 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
16390 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
163a0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
163b0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
163c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
163d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
163e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
163f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
16400 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
16410 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
16420 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
16430 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
16440 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
16450 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
16460 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
16470 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
16480 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
16490 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
164a0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
164b0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
164c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
164d0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
164e0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
164f0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
16500 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
16510 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16520 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
16530 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
16540 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
16550 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16560 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
16570 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
16580 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
16590 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
165a0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
165b0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
165c0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
165d0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
165e0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
165f0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
16600 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
16610 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
16620 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
16630 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
16640 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
16650 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
16660 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
16670 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
16680 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
16690 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
166a0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
166b0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
166c0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
166d0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
166e0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
166f0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
16700 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
16710 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
16720 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
16730 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16740 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
16750 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
16760 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
16770 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
16780 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
16790 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
167a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
167b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
167c0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
167d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
167e0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
167f0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
16800 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
16810 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
16820 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
16830 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
16840 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
16850 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
16860 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
16870 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
16880 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
16890 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
168a0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
168b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
168c0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
168d0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
168e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
168f0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
16900 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
16910 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
16920 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
16930 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
16940 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
16950 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
16960 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
16970 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
16980 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
16990 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
169a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
169b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
169c0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
169d0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
169e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
169f0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
16a00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
16a10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
16a20 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
16a30 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
16a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
16a50 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
16a60 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
16a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
16a80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
16a90 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
16aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
16ab0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
16ac0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
16ad0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
16ae0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
16af0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
16b00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
16b10 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
16b20 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
16b30 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
16b40 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
16b50 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
16b60 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
16b70 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
16b80 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
16b90 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
16ba0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
16bb0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
16bc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16bd0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
16be0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
16bf0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
16c00 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
16c10 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
16c20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
16c30 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
16c40 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
16c50 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
16c60 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
16c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16c80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16c90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
16ca0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
16cb0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
16cc0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
16cd0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
16ce0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
16cf0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
16d00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
16d10 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
16d20 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
16d30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
16d40 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
16d50 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
16d60 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
16d70 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
16d80 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
16d90 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
16da0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
16db0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
16dc0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
16dd0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
16de0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
16df0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
16e00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16e10 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
16e20 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
16e30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
16e40 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
16e50 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
16e60 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
16e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
16e80 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
16e90 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
16ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
16eb0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
16ec0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
16ed0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
16ee0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
16ef0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
16f00 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
16f10 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
16f20 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
16f30 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
16f40 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
16f50 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
16f60 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
16f70 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
16f80 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
16f90 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
16fa0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
16fb0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
16fc0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
16fd0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
16fe0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
16ff0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
17000 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
17010 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
17020 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
17030 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
17040 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
17050 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
17060 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
17070 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
17080 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
17090 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
170a0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
170b0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
170c0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
170d0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
170e0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
170f0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
17100 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
17110 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
17120 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
17130 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
17140 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
17150 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
17160 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
17170 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
17180 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
17190 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
171a0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
171b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
171c0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
171d0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
171e0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
171f0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
17200 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
17210 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
17220 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
17230 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
17240 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
17250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
17260 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
17270 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
17280 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
17290 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
172a0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
172b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
172c0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
172d0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
172e0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
172f0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
17300 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
17310 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
17320 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
17330 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
17340 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
17350 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
17360 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
17370 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
17380 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
17390 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
173a0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
173b0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
173c0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
173d0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
173e0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
173f0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
17400 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
17410 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
17420 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
17430 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
17440 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
17450 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
17460 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
17470 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
17480 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
17490 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
174a0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
174b0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
174c0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
174d0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
174e0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
174f0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
17500 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
17510 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
17520 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
17530 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
17540 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
17550 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
17560 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
17570 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
17580 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
17590 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
175a0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
175b0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
175c0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
175d0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
175e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
175f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
17600 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
17610 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
17620 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17630 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
17640 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
17650 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
17660 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
17670 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
17680 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
17690 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
176a0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
176b0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
176c0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
176d0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
176e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
176f0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
17700 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
17710 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17730 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
17740 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17750 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
17760 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
17770 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
17780 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
17790 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
177a0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
177b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177c0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
177d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
177e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
177f0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
17800 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
17810 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17820 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
17830 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
17840 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
17850 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
17860 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
17870 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
17880 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
17890 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
178a0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
178b0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
178c0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
178d0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
178e0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
178f0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
17900 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
17910 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
17920 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
17930 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
17940 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
17950 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
17960 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
17970 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
17980 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
17990 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
179a0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
179b0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
179c0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
179d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
179e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
179f0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
17a00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
17a10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
17a20 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
17a30 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
17a40 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
17a50 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
17a60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
17a70 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
17a80 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
17a90 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
17aa0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
17ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
17ac0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
17ad0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
17ae0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
17af0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
17b00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
17b10 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
17b20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
17b30 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
17b40 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
17b50 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
17b60 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
17b70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
17b80 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
17b90 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
17ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17bb0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
17bc0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
17bd0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
17be0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
17bf0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
17c00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
17c10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
17c20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
17c30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17c40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
17c50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
17c60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
17c70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
17c80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
17c90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
17ca0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
17cb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
17cc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
17cd0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
17ce0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
17cf0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
17d00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
17d10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
17d20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
17d30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
17d40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
17d50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
17d60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
17d70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
17d80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
17d90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
17da0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
17db0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
17dc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
17dd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
17de0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
17df0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
17e00 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
17e10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
17e20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
17e30 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
17e40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
17e50 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
17e60 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
17e70 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
17e80 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
17e90 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
17ea0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
17eb0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
17ec0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
17ed0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
17ee0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
17ef0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
17f00 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
17f10 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
17f20 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
17f30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
17f40 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
17f50 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
17f60 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
17f70 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
17f80 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
17f90 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17fb0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
17fc0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
17fd0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
17fe0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
17ff0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
18000 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
18010 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
18020 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
18030 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18040 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
18050 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
18060 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
18070 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
18080 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
18090 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
180a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
180b0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
180c0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
180d0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
180e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
180f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18100 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
18110 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
18120 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
18130 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
18140 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
18150 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
18160 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
18170 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
18180 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
18190 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
181a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
181b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
181c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
181d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
181e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
181f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
18200 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
18210 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18220 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
18230 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
18240 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
18250 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
18260 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
18270 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18280 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
18290 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
182a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
182b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
182c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
182d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
182e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
182f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18300 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
18310 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
18320 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
18330 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
18340 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
18350 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
18360 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
18370 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
18380 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
18390 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
183a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
183b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
183c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
183d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
183e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
183f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
18400 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
18410 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
18420 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18430 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
18440 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
18450 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
18460 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
18470 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
18480 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
18490 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
184a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
184b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
184c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
184d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
184e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
184f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
18500 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18510 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
18520 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18530 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
18540 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
18550 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
18560 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
18570 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
18580 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
18590 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
185a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
185b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
185c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
185d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
185e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
185f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
18600 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
18610 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
18620 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
18630 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
18640 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
18650 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
18660 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
18670 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
18680 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
18690 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
186a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
186b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
186c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
186d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
186e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
186f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
18700 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
18710 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
18720 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
18730 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
18740 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
18750 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
18760 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
18770 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
18780 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
18790 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
187a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
187b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
187c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
187d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
187e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
187f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
18800 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
18810 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18820 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
18830 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
18840 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
18850 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
18860 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
18870 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
18880 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
18890 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
188a0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
188b0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
188c0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
188d0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
188e0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
188f0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
18900 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
18910 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
18920 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
18930 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
18940 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
18950 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
18960 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
18970 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
18980 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
18990 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
189a0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
189b0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
189c0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
189d0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
189e0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
189f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18a00 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
18a10 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
18a20 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
18a30 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
18a40 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
18a50 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
18a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
18a70 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
18a80 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
18a90 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
18aa0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
18ab0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
18ac0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
18ad0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
18ae0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
18af0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
18b00 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
18b10 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
18b20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
18b30 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
18b40 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
18b50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
18b60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
18b70 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
18b80 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
18b90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
18ba0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
18bb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
18bc0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
18bd0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
18be0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
18bf0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
18c00 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
18c10 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
18c20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
18c30 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
18c40 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
18c50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
18c60 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
18c70 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
18c80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
18c90 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
18ca0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
18cb0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
18cc0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
18cd0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
18ce0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
18cf0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
18d00 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
18d10 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
18d20 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
18d30 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
18d40 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
18d50 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
18d60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18d70 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
18d80 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
18d90 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
18da0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
18db0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
18dc0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
18dd0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
18de0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
18df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
18e00 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
18e10 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
18e20 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
18e30 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
18e40 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
18e50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18e60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
18e70 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
18e80 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
18e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
18ea0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
18eb0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
18ec0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
18ed0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
18ee0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
18ef0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
18f00 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
18f10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18f20 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
18f30 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
18f40 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
18f50 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
18f60 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
18f70 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
18f80 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
18f90 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
18fa0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
18fb0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
18fc0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
18fd0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
18fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18ff0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
19000 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
19010 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
19020 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
19030 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19040 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
19050 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
19060 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
19070 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
19080 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
19090 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
190a0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
190b0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
190c0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
190d0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
190e0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
190f0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
19100 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
19110 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
19120 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
19130 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
19140 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
19150 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
19160 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
19170 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
19180 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
19190 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
191a0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
191b0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
191c0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
191d0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
191e0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
191f0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
19200 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
19210 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
19220 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
19230 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
19240 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
19250 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
19260 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
19270 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
19280 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
19290 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
192a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
192b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
192c0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
192d0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
192e0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
192f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
19300 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
19310 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
19320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
19330 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19340 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19350 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
19360 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
19370 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
19380 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
19390 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
193a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
193b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
193c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
193d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
193e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
193f0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
19400 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
19410 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
19420 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
19430 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
19440 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
19450 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
19460 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
19470 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19480 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
19490 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
194a0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
194b0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
194c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
194d0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
194e0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
194f0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
19500 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
19510 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
19520 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
19530 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
19540 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
19550 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
19560 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
19570 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
19580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
19590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
195a0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
195b0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
195c0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
195d0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
195e0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
195f0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
19600 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
19610 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
19620 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
19630 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
19640 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
19650 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
19660 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
19670 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
19680 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
19690 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
196a0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
196b0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
196c0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
196d0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
196e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
196f0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
19700 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
19710 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
19720 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
19730 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
19740 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
19750 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19760 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
19770 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
19780 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
19790 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
197a0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
197b0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
197c0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
197d0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
197e0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
197f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19800 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
19810 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
19820 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
19830 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
19840 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
19850 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
19860 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
19870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
19880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
19890 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
198a0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
198b0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
198c0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
198d0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
198e0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
198f0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
19900 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
19910 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19920 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
19930 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
19940 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
19950 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
19960 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
19970 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
19980 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
19990 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
199a0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
199b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
199c0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
199d0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
199e0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
199f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
19a00 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
19a10 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
19a20 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
19a30 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
19a40 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
19a50 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
19a60 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
19a70 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
19a80 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
19a90 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
19aa0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
19ab0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19ac0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
19ad0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
19ae0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
19af0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
19b00 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
19b10 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
19b20 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
19b30 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
19b40 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
19b50 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
19b60 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
19b70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
19b80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19b90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
19ba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
19bb0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
19bc0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
19bd0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
19be0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
19bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
19c00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19c10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
19c20 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
19c30 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
19c40 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
19c50 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
19c60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
19c70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
19c80 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
19c90 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
19ca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19cb0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
19cc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
19cd0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
19ce0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
19cf0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
19d00 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
19d10 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d20 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
19d30 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
19d40 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
19d50 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
19d60 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
19d70 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
19d80 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
19d90 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
19da0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
19db0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
19dc0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
19dd0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
19de0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
19df0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
19e00 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
19e10 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
19e20 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
19e30 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
19e40 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
19e50 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
19e60 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
19e70 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
19e80 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
19e90 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
19ea0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
19eb0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
19ec0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
19ed0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
19ee0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
19ef0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
19f00 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
19f10 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
19f20 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
19f30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
19f40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19f50 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
19f60 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
19f70 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
19f80 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
19f90 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
19fa0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
19fb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
19fc0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
19fd0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
19fe0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
19ff0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1a000 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a010 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1a020 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1a030 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1a040 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1a050 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1a060 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1a070 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1a080 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1a090 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1a0a0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1a0b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1a0c0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1a0d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1a0e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1a0f0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1a100 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a110 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1a120 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1a130 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1a140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1a150 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1a160 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1a170 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1a180 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1a190 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1a1a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1a1b0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1a1c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1a1d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1a1e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1a1f0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1a200 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1a210 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1a220 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1a230 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1a240 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1a250 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1a260 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1a270 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1a280 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1a290 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1a2a0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1a2b0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1a2c0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1a2d0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1a2e0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1a2f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1a300 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1a310 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a320 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1a330 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1a340 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1a350 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1a360 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1a370 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a380 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1a390 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1a3a0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1a3b0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1a3c0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1a3d0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1a3e0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1a3f0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1a400 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1a410 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1a420 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1a430 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1a440 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1a450 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1a460 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1a470 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1a480 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1a490 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1a4a0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1a4b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1a4c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1a4d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1a4e0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1a4f0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1a500 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1a510 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1a520 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1a530 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1a540 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1a550 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1a560 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1a570 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1a580 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1a590 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1a5a0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1a5b0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1a5c0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1a5d0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1a5e0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1a5f0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1a600 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1a610 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1a620 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1a630 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1a640 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1a650 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1a660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1a670 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1a680 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1a690 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1a6a0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1a6b0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1a6c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1a6d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1a6e0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1a6f0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1a700 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1a710 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1a720 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a730 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1a740 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1a750 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1a760 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1a770 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1a780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a790 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1a7a0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1a7b0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1a7c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1a7d0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1a7e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1a7f0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1a800 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1a810 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1a820 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1a830 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1a840 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a850 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1a860 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1a870 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1a880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1a890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1a8a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1a8b0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1a8c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1a8e0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a8f0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1a900 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1a910 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1a920 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1a930 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1a940 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1a950 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1a960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1a970 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1a980 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1a990 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a9a0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1a9b0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1a9c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1a9d0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1a9e0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1a9f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1aa00 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1aa10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1aa20 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1aa30 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1aa40 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1aa50 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1aa60 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1aa70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1aa80 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1aa90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1aaa0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1aab0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1aac0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1aad0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1aae0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1aaf0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1ab00 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1ab10 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ab20 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1ab30 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1ab40 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1ab50 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1ab60 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1ab70 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1ab80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ab90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1aba0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1abb0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1abc0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1abd0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1abe0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1abf0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1ac00 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1ac10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1ac20 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1ac30 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1ac40 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1ac50 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1ac60 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1ac70 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1ac80 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1ac90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1aca0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1acb0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1acc0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1acd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ace0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1acf0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1ad00 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1ad10 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1ad20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
1ad30 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ad40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1ad50 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1ad60 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1ad70 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ad80 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1ad90 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1ada0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1adb0 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1adc0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1add0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1ade0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1adf0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1ae00 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1ae10 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1ae20 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1ae30 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1ae40 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1ae50 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1ae60 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1ae70 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1ae80 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1ae90 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1aea0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1aeb0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1aec0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1aed0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1aee0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1aef0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1af00 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1af10 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1af20 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1af30 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1af40 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1af50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1af60 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1af70 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1af80 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1af90 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1afa0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1afb0 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1afc0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1afd0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1afe0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1aff0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1b000 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1b010 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1b020 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1b030 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1b040 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b050 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1b060 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1b070 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1b080 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1b090 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1b0a0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1b0b0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1b0c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1b0d0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1b0e0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
1b0f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1b100 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1b110 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1b120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b130 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1b140 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1b150 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1b160 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1b170 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1b180 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1b190 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b1a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b1b0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1b1c0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1b1d0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1b1e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b1f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1b200 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1b210 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1b220 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1b230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b240 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1b250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b260 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1b270 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1b280 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1b290 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1b2a0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1b2b0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1b2c0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1b2d0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1b2e0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1b2f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1b300 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1b310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b320 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1b330 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1b340 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1b350 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1b360 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b370 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1b380 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1b390 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1b3a0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1b3b0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1b3c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1b3d0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1b3e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b3f0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1b400 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1b410 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1b420 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1b430 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1b440 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1b450 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1b460 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1b470 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b480 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1b490 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1b4a0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1b4b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1b4c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1b4d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1b4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b4f0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1b500 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1b510 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1b520 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1b530 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b540 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1b550 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1b560 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1b570 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1b580 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1b590 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1b5a0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1b5b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b5c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1b5d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1b5e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b5f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1b600 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1b610 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1b620 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1b630 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1b640 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1b650 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1b660 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1b670 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1b680 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1b690 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b6a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1b6b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1b6c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1b6d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1b6e0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1b6f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b700 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1b710 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1b720 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1b730 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1b740 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1b750 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1b760 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1b770 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1b780 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1b790 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1b7a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1b7b0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1b7c0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1b7d0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1b7e0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1b7f0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1b800 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1b810 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b820 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1b830 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1b840 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1b850 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b860 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1b870 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1b880 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1b890 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1b8a0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1b8b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1b8c0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1b8d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1b8e0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1b8f0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1b900 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1b910 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1b920 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1b930 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1b940 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1b950 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1b960 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1b970 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1b980 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1b990 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1b9a0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1b9b0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1b9c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b9d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1b9e0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1b9f0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1ba00 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1ba10 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1ba20 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1ba30 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1ba40 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1ba50 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1ba60 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1ba70 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1ba80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ba90 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1baa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bab0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1bac0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1bad0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1bae0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1baf0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1bb00 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1bb10 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1bb20 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1bb30 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1bb40 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1bb50 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1bb60 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1bb70 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1bb80 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1bb90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1bba0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1bbb0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1bbc0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1bbd0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1bbe0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1bbf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bc00 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1bc10 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1bc20 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1bc30 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1bc40 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1bc50 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1bc60 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1bc70 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1bc80 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1bc90 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1bca0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1bcb0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1bcc0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1bcd0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1bce0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1bcf0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1bd00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1bd10 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1bd20 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1bd30 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1bd40 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1bd50 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1bd60 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1bd70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1bd80 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1bd90 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1bda0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1bdb0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1bdc0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1bdd0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1bde0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1bdf0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1be00 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1be10 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1be20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1be30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1be40 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1be50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1be60 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1be70 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1be80 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1be90 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1bea0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1beb0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1bec0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1bed0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1bee0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1bef0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1bf00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1bf10 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1bf20 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1bf30 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1bf40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bf50 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1bf60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1bf70 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1bf80 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1bf90 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1bfa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1bfb0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1bfc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bfd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1bfe0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1bff0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1c000 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1c010 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c020 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1c030 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1c040 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1c050 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1c060 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1c070 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1c080 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1c090 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1c0a0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1c0b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1c0c0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1c0d0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1c0e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c0f0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1c100 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1c110 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c120 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1c130 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c140 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c150 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1c160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c170 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c180 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1c190 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1c1a0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1c1b0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1c1c0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1c1d0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1c1e0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1c1f0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1c200 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1c210 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1c220 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1c230 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1c240 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1c250 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1c260 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
1c270 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1c280 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c290 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1c2a0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1c2b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1c2c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c2d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c2e0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1c2f0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1c300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c310 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1c320 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1c330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1c340 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1c350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c360 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1c370 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1c380 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1c390 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1c3a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1c3b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1c3c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1c3d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1c3e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1c3f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1c400 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1c410 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1c420 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1c430 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1c440 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1c450 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1c460 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1c470 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1c480 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1c490 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1c4a0 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1c4b0 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1c4c0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1c4d0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1c4e0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1c4f0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1c500 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1c510 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1c520 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1c530 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1c540 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1c550 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1c560 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1c570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1c580 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1c590 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1c5a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c5b0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1c5c0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1c5d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c5e0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1c5f0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1c600 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1c610 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1c620 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1c630 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1c650 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1c660 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1c670 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1c680 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1c690 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1c6a0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1c6b0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1c6c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c6d0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1c6e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1c6f0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1c700 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1c710 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1c720 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1c730 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1c740 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1c750 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1c760 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1c770 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1c780 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1c790 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1c7a0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1c7b0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1c7c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1c7d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1c7e0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1c7f0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1c800 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c810 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1c820 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1c830 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1c840 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1c850 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1c860 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1c870 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c880 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1c890 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1c8a0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1c8b0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1c8c0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1c8d0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1c8e0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1c8f0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1c900 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1c910 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1c920 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1c930 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1c940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1c960 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1c970 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1c980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c990 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1c9a0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1c9b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1c9c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c9d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c9e0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1c9f0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1ca00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ca10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ca20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ca30 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1ca40 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1ca50 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ca60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ca70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ca80 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1ca90 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1caa0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1cab0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1cad0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1cae0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1caf0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1cb00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1cb10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1cb20 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1cb30 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1cb40 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1cb50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cb60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1cb70 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1cb80 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1cb90 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1cba0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1cbb0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1cbc0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1cbd0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1cbe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cbf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cc00 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1cc10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1cc20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1cc30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1cc40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cc50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1cc60 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1cc70 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1cc80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1cc90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cca0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1ccb0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1ccc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ccd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1cce0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ccf0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1cd00 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1cd10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1cd20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1cd30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cd40 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1cd50 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1cd60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cd70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cd80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cd90 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1cda0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1cdb0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1cdc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cdd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cde0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1cdf0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1ce00 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1ce10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ce20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ce30 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1ce40 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1ce50 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ce60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ce70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ce80 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1ce90 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1cea0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ceb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1ced0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1cee0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1cef0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1cf00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cf10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1cf20 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1cf30 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1cf40 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1cf50 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1cf60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1cf70 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1cf80 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1cf90 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1cfa0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cfb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1cfc0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1cfd0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1cfe0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1cff0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d000 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1d010 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1d020 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1d030 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1d040 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d050 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1d060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1d070 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1d080 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1d090 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1d0a0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1d0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1d0c0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1d0d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d0e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d0f0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1d100 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1d110 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1d120 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1d130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d140 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1d150 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1d160 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1d170 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1d180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d190 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1d1a0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1d1b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d1c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d1d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d1e0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1d1f0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1d200 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d230 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1d240 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1d250 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d260 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1d270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d280 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1d290 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1d2a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d2b0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1d2c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d2d0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1d2e0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1d2f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1d300 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1d310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d320 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1d330 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1d340 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1d350 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1d360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d370 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1d380 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1d390 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1d3a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d3b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1d3c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1d3d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d3e0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1d3f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1d400 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1d410 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1d420 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1d430 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1d440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1d450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1d460 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1d470 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1d480 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1d490 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1d4a0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1d4b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1d4c0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1d4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d4e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1d4f0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1d500 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1d510 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1d520 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1d530 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1d540 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1d550 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1d560 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1d570 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1d580 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1d590 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1d5a0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1d5b0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1d5c0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1d5d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1d5e0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1d5f0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1d600 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1d610 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1d620 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1d630 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1d640 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1d650 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1d660 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1d670 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1d680 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1d690 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1d6a0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1d6b0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1d6c0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1d6d0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1d6e0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1d6f0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1d700 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1d710 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1d720 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1d730 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1d740 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1d750 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1d760 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1d770 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1d780 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1d790 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1d7a0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1d7b0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1d7c0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1d7d0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1d7e0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1d7f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d800 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1d810 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1d820 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1d830 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1d840 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1d850 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1d860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1d870 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1d880 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1d890 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1d8a0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1d8b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1d8c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1d8d0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1d8e0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1d8f0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1d900 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1d910 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1d920 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1d930 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1d940 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1d950 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1d960 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1d970 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1d980 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1d990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d9a0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1d9b0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1d9c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1d9d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1d9e0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1d9f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1da00 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1da10 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1da20 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1da30 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1da40 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1da50 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1da60 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1da70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1da80 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1da90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1daa0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1dab0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1dac0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1dad0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1dae0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1daf0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1db00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1db10 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1db20 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1db30 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1db40 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1db50 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1db60 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1db70 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1db80 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1db90 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1dba0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1dbb0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1dbc0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1dbd0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1dbe0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1dbf0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1dc00 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1dc10 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1dc20 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1dc30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1dc40 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1dc50 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1dc60 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1dc70 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1dc80 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1dc90 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1dca0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1dcb0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1dcc0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1dcd0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1dce0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1dcf0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1dd00 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1dd10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1dd20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1dd30 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1dd40 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1dd50 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1dd60 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1dd70 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1dd80 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1dd90 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1dda0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1ddb0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1ddc0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1ddd0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1dde0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1ddf0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1de00 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1de10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1de20 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1de30 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1de40 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1de50 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1de60 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1de70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1de80 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1de90 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1dea0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1deb0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1dec0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1ded0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
1dee0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1def0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1df00 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1df10 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1df20 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1df30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1df40 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1df50 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1df60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1df70 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1df80 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1df90 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1dfa0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1dfb0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1dfc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1dfd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1dfe0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1dff0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1e000 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1e010 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1e020 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e030 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1e040 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1e050 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1e060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e070 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1e080 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1e090 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1e0a0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1e0b0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1e0c0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1e0d0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1e0e0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1e0f0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1e100 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1e110 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1e120 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1e130 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1e140 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1e150 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1e160 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1e170 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1e180 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1e190 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1e1a0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1e1b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1e1c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1e1d0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1e1e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1e1f0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1e200 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1e210 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1e220 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1e230 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1e240 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1e250 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1e260 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1e270 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1e280 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1e290 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1e2a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1e2b0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1e2c0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1e2d0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1e2e0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1e2f0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1e300 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1e310 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1e320 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1e330 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1e340 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1e350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e360 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1e370 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1e380 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1e390 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1e3a0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1e3b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1e3c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1e3d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1e3e0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1e3f0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1e400 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1e410 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1e420 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1e430 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1e440 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1e450 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1e460 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1e470 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1e480 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1e490 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1e4a0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1e4b0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1e4c0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1e4d0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1e4e0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1e4f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1e500 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1e510 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1e520 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1e530 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1e540 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1e550 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1e560 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1e570 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1e580 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1e590 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1e5a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1e5b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1e5c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
1e5d0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1e5e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
1e5f0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1e600 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e610 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1e620 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1e630 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e640 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1e650 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1e660 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1e670 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1e680 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1e690 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1e6a0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1e6b0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e6c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e6d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e6e0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1e6f0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1e700 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1e710 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1e720 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1e730 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1e740 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e750 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1e760 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1e770 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1e780 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1e790 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1e7a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1e7b0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1e7c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1e7d0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1e7e0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1e7f0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e800 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1e810 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1e820 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1e830 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
1e840 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1e850 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1e860 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1e870 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1e880 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1e890 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1e8a0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
1e8b0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
1e8c0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1e8d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e8e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1e8f0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1e900 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1e910 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
1e920 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1e930 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
1e940 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1e950 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
1e960 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
1e970 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1e980 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1e990 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1e9a0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1e9b0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1e9c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e9d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1e9e0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1e9f0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1ea00 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1ea10 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1ea20 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1ea30 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1ea40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1ea50 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1ea60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1ea70 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1ea80 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1ea90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1eaa0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1eab0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1eac0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1ead0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1eae0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1eaf0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1eb00 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1eb10 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1eb20 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1eb30 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1eb40 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1eb50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1eb60 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1eb70 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1eb80 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1eb90 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1eba0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1ebb0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1ebc0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1ebd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1ebe0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1ebf0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1ec00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1ec10 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1ec20 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1ec30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1ec40 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1ec50 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1ec60 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1ec70 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1ec90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1eca0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ecb0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1ecc0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1ecd0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1ece0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1ecf0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1ed00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1ed10 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1ed20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1ed30 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1ed40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1ed50 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1ed60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1ed70 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1ed80 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1ed90 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
1eda0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1edb0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1edc0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1edd0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1ede0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1edf0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1ee00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1ee10 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1ee20 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1ee30 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1ee40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ee50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1ee60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1ee70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1ee80 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1ee90 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1eea0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1eeb0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1eec0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1eed0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1eee0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1eef0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ef00 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1ef10 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1ef20 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1ef30 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1ef40 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1ef50 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1ef60 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1ef70 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1ef80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1ef90 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1efa0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1efb0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1efc0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1efd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1efe0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1eff0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1f000 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1f010 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1f020 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1f030 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f040 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1f050 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
1f060 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
1f070 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
1f080 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
1f090 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
1f0a0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
1f0b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1f0c0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
1f0d0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1f0e0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
1f0f0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
1f100 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
1f110 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
1f120 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
1f130 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1f140 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
1f150 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1f160 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
1f170 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
1f180 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1f190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f1a0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
1f1b0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
1f1c0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
1f1d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
1f1e0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
1f1f0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
1f200 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
1f210 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
1f220 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
1f230 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1f240 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
1f250 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f260 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
1f270 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1f280 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
1f290 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
1f2a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
1f2b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1f2c0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
1f2d0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
1f2e0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
1f2f0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
1f300 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
1f310 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f320 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
1f330 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
1f340 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
1f350 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
1f360 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
1f370 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
1f380 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
1f390 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
1f3a0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
1f3b0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
1f3c0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
1f3d0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
1f3e0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
1f3f0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
1f400 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
1f410 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
1f420 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
1f430 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
1f440 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
1f450 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
1f460 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1f470 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1f480 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
1f490 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
1f4a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
1f4b0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
1f4c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
1f4d0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
1f4e0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
1f4f0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
1f500 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
1f510 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1f520 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
1f530 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
1f540 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
1f550 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
1f560 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
1f570 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
1f580 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
1f590 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
1f5a0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
1f5b0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
1f5c0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
1f5d0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
1f5e0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
1f5f0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
1f600 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
1f610 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
1f620 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
1f630 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
1f640 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1f650 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
1f660 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1f670 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
1f680 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
1f690 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
1f6a0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
1f6b0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
1f6c0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
1f6d0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
1f6e0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
1f6f0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
1f700 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1f710 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1f720 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1f730 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
1f740 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
1f750 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
1f760 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
1f770 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
1f780 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
1f790 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
1f7a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1f7b0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1f7c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
1f7d0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
1f7e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1f7f0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
1f800 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
1f810 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
1f820 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
1f830 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
1f840 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
1f850 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
1f860 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
1f870 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
1f880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f890 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
1f8a0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
1f8b0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
1f8c0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
1f8d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
1f8e0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
1f8f0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
1f900 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
1f910 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
1f920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f930 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1f940 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1f950 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
1f960 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1f970 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
1f980 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
1f990 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
1f9a0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
1f9b0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
1f9c0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
1f9d0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
1f9e0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
1f9f0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
1fa00 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
1fa10 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1fa20 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
1fa30 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
1fa40 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
1fa50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1fa60 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
1fa70 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
1fa80 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
1fa90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1faa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1fab0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
1fac0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
1fad0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
1fae0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1faf0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1fb00 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
1fb10 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
1fb20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
1fb30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1fb40 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
1fb50 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1fb60 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
1fb70 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
1fb80 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
1fb90 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
1fba0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
1fbb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fbc0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
1fbd0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
1fbe0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1fbf0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
1fc00 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
1fc10 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
1fc20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
1fc30 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
1fc40 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
1fc50 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
1fc60 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
1fc70 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
1fc80 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
1fc90 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1fca0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
1fcb0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
1fcc0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
1fcd0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
1fce0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
1fcf0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
1fd00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fd10 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
1fd20 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
1fd30 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
1fd40 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
1fd50 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
1fd60 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
1fd70 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
1fd80 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
1fd90 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1fda0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
1fdb0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
1fdc0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
1fdd0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
1fde0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
1fdf0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
1fe00 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
1fe10 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
1fe20 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
1fe30 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
1fe40 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1fe50 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
1fe60 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1fe70 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
1fe80 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
1fe90 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
1fea0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
1feb0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
1fec0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
1fed0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
1fee0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
1fef0 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71  ny behaviour req
1ff00 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
1ff10 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
1ff20 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1ff30 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
1ff40 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
1ff50 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
1ff60 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
1ff70 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
1ff80 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
1ff90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1ffa0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
1ffb0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
1ffc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1ffd0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
1ffe0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
1fff0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
20000 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
20010 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
20020 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
20030 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
20040 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
20050 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20060 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
20070 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
20080 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20090 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
200a0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
200b0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
200c0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
200d0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
200e0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
200f0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
20100 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
20110 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20120 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
20130 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
20140 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
20150 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20160 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
20170 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
20180 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
20190 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
201a0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
201b0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
201c0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
201d0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
201e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
201f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20200 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
20210 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
20220 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
20230 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
20240 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
20250 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
20260 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
20270 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
20280 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
20290 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
202a0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
202b0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
202c0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
202d0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
202e0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
202f0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
20300 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
20310 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
20320 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
20330 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
20340 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
20350 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
20360 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
20370 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
20380 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
20390 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
203a0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
203b0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
203c0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
203d0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
203e0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
203f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20400 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
20410 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
20420 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
20430 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
20440 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
20450 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
20460 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
20470 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
20480 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
20490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
204a0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
204b0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
204c0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
204d0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
204e0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
204f0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
20500 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
20510 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
20520 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
20530 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
20540 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
20550 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
20560 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
20570 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
20580 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
20590 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
205a0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
205b0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
205c0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
205d0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
205e0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
205f0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
20600 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
20610 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
20620 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
20630 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
20640 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
20650 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
20660 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
20670 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
20680 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
20690 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
206a0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
206b0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
206c0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
206d0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
206e0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
206f0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
20700 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
20710 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
20720 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
20730 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
20740 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
20750 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
20760 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
20770 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
20780 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
20790 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
207a0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
207b0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
207c0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
207d0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
207e0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
207f0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
20800 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
20810 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
20820 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
20830 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
20840 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
20850 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
20860 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
20870 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
20880 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20890 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
208a0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
208b0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
208c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
208d0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
208e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
208f0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
20900 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
20910 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
20920 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
20930 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
20940 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20950 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
20960 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  v2()..*/.SQLITE_
20970 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20980 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
20990 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
209a0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
209b0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
209c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
209d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
209e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
209f0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
20a00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20a10 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
20a20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
20a30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
20a40 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
20a50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20a60 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
20a70 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20a80 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
20a90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
20aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
20ab0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
20ac0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
20ad0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
20ae0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
20af0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
20b00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
20b10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
20b20 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
20b30 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
20b40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
20b50 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
20b60 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
20b70 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
20b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20b90 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
20ba0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
20bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
20bc0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
20bd0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
20be0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
20bf0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
20c00 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
20c10 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
20c20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
20c30 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
20c40 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
20c50 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
20c60 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
20c70 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
20c80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
20c90 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
20ca0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
20cb0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
20cc0 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
20cd0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
20ce0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
20cf0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
20d00 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
20d10 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
20d20 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
20d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20d40 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
20d50 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
20d60 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
20d70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
20d80 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
20d90 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
20da0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
20db0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
20dc0 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
20dd0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
20de0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
20df0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
20e00 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
20e10 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
20e20 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
20e30 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
20e40 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
20e50 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
20e60 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
20e70 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
20e80 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
20e90 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
20ea0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
20eb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20ec0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
20ed0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
20ee0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
20ef0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
20f00 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
20f10 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
20f20 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
20f30 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
20f40 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
20f50 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20f60 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
20f70 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
20f80 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
20f90 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
20fa0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
20fb0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
20fc0 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
20fd0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
20fe0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
20ff0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
21000 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
21010 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21020 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
21030 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
21040 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
21050 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
21060 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
21070 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
21080 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
21090 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
210a0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
210b0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
210c0 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
210d0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
210e0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
210f0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
21100 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
21110 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
21120 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
21130 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21140 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
21150 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
21160 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
21170 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
21180 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
21190 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
211a0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
211b0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
211c0 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
211d0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
211e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
211f0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
21200 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
21210 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
21220 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
21230 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
21240 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
21250 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
21260 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
21270 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
21280 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
21290 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
212a0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
212b0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
212c0 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
212d0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
212e0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
212f0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
21300 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
21310 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
21320 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
21330 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
21340 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
21350 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
21360 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
21370 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
21380 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
21390 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
213a0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
213b0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
213c0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
213d0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
213e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
213f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
21400 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
21410 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
21420 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
21430 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45  Default);.SQLITE
21440 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
21450 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
21460 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
21470 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
21480 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
21490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
214a0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
214b0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
214c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
214d0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
214e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
214f0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
21500 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
21510 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
21520 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
21530 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
21540 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
21550 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
21560 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
21570 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
21580 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
21590 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
215a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
215b0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
215c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
215d0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
215e0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
215f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
21600 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
21610 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
21620 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
21630 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
21640 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
21650 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
21660 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
21670 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
21680 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
21690 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
216a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
216b0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
216c0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
216d0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
216e0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
216f0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
21700 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
21710 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
21720 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
21730 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
21740 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
21750 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
21760 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
21770 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
21780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
21790 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
217a0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
217b0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
217c0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
217d0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
217e0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
217f0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
21800 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
21810 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
21820 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
21830 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
21840 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
21850 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
21860 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
21870 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
21880 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
21890 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
218a0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
218b0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
218c0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
218d0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
218e0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
218f0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
21900 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
21910 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
21920 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
21930 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
21940 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
21950 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
21960 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
21970 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
21980 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
21990 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
219a0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
219b0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
219c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
219d0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
219e0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
219f0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
21a00 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
21a10 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
21a20 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
21a30 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
21a40 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
21a50 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
21a60 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
21a70 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
21a80 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
21a90 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
21aa0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
21ab0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
21ac0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
21ad0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
21ae0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
21af0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
21b00 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
21b10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
21b20 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
21b30 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
21b40 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
21b50 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
21b60 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
21b70 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
21b80 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
21b90 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
21ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
21bb0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
21bc0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
21bd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
21be0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
21bf0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
21c00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
21c10 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
21c20 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
21c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21c40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
21c50 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
21c60 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
21c70 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
21c80 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
21c90 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
21ca0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
21cb0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
21cc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
21cd0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
21ce0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
21cf0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
21d00 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
21d10 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
21d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
21d30 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
21d40 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
21d50 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
21d60 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
21d70 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
21d80 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
21d90 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
21da0 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
21db0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21dc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
21dd0 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
21de0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
21df0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
21e00 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
21e10 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
21e20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
21e30 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
21e40 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
21e50 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
21e60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21e70 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
21e80 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
21e90 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
21ea0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21eb0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
21ec0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
21ed0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
21ee0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
21ef0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
21f00 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
21f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21f20 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
21f30 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
21f40 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
21f50 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
21f60 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
21f70 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
21f80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
21f90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
21fa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
21fb0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
21fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
21fd0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
21fe0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
21ff0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
22000 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
22010 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
22020 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
22030 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
22040 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
22050 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22060 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
22070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22080 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
22090 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
220a0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
220b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
220c0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
220d0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
220e0 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
220f0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
22100 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
22110 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
22120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22130 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
22140 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
22150 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
22160 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
22170 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
22180 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
22190 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
221a0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
221b0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
221c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
221d0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
221e0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
221f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
22200 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
22210 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
22220 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
22230 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
22240 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
22250 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
22260 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
22270 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
22280 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
22290 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
222a0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
222b0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
222c0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
222d0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
222e0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
222f0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
22300 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
22310 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
22320 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
22330 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
22340 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
22350 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
22360 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22370 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
22380 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
22390 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
223a0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
223b0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
223c0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
223d0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
223e0 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
223f0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
22400 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
22410 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
22420 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
22430 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
22440 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
22450 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
22460 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
22470 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
22480 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
22490 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
224a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
224b0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
224c0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
224d0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
224e0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
224f0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
22500 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
22510 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
22520 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
22530 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
22540 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
22550 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
22560 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
22570 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
22580 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
22590 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
225a0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
225b0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
225c0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
225d0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
225e0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
225f0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
22600 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
22610 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
22620 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
22630 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
22640 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
22650 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
22660 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
22670 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
22680 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
22690 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
226a0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
226b0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
226c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
226d0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
226e0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
226f0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
22700 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
22710 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
22720 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
22730 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
22740 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
22750 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
22760 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
22770 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
22780 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22790 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
227a0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
227b0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
227c0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
227d0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
227e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
227f0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
22800 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
22810 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
22820 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
22830 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
22840 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
22850 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
22860 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
22870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
22880 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
22890 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
228a0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
228b0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
228c0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
228d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
228e0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
228f0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
22900 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
22910 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
22920 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22930 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
22940 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
22950 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22960 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
22970 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
22980 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
22990 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
229a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
229b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
229c0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
229d0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
229e0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
229f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22a00 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
22a10 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
22a20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
22a30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
22a40 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
22a50 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
22a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22a70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22a80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
22a90 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
22aa0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
22ab0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
22ac0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
22ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22ae0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
22af0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
22b00 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
22b10 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
22b20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22b30 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22b40 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
22b50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22b60 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
22b70 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
22b80 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
22b90 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
22ba0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
22bb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22bc0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
22bd0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
22be0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
22bf0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
22c00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22c10 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
22c20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
22c30 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
22c40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22c60 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
22c70 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
22c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22c90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22ca0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
22cb0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
22cc0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
22cd0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
22ce0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
22cf0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
22d00 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
22d10 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
22d20 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
22d30 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
22d40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
22d50 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
22d60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22d70 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
22d80 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
22d90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
22da0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
22db0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22dc0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
22dd0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
22de0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22df0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22e00 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
22e10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
22e20 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
22e30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22e40 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
22e50 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
22e60 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
22e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22e80 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
22e90 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
22ea0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22eb0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
22ec0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22ed0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22ee0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
22ef0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
22f00 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
22f10 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
22f20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
22f40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
22f50 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
22f60 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
22f70 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
22f80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
22f90 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
22fa0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
22fb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
22fc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
22fd0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
22fe0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
22ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23000 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
23010 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23020 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
23030 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
23040 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
23050 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
23060 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
23070 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23080 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
23090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
230a0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
230b0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
230c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
230d0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
230e0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
230f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
23100 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
23110 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23120 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
23130 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
23140 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
23150 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23160 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
23170 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
23180 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23190 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
231a0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
231b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
231c0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
231d0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
231e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
231f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23200 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
23210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23220 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23230 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
23240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23250 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
23260 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
23270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23280 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
23290 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
232a0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
232b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
232c0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
232d0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
232e0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
232f0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
23300 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
23310 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23320 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23330 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
23340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
23350 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
23360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23370 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
23380 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
23390 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
233a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
233b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
233c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
233d0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
233e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
233f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
23400 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
23410 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23420 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
23430 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
23440 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23450 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
23460 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
23470 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
23480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
234a0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
234b0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
234c0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
234d0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
234e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
234f0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
23500 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
23510 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23520 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
23530 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
23540 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
23550 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
23560 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
23570 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23580 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
23590 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
235a0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
235b0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
235c0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
235d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
235e0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
235f0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
23600 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
23610 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23620 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
23630 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
23640 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
23650 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
23660 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
23670 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
23680 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
23690 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
236a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
236b0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
236c0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
236d0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
236e0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
236f0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23700 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23710 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23720 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23730 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
23740 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
23750 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
23760 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
23770 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
23780 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
23790 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
237a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
237b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
237c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
237d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
237e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
237f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
23800 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
23810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
23820 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
23830 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
23840 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
23850 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
23860 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
23870 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
23880 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
23890 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
238a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
238b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
238c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
238d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
238e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
238f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
23900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23910 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
23920 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
23930 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
23940 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
23950 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
23960 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
23970 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
23980 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
23990 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
239a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
239b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
239c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
239d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
239e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
239f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
23a00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23a10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23a20 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
23a30 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
23a40 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
23a50 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
23a60 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
23a70 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
23a80 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
23a90 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
23aa0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
23ab0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
23ac0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
23ad0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
23af0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
23b00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23b10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
23b20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
23b30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
23b40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
23b50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
23b60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
23b70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
23b80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
23b90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
23ba0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
23bb0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
23bc0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
23bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
23be0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
23bf0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
23c00 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
23c10 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
23c20 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
23c30 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
23c40 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
23c50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
23c60 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
23c70 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
23c80 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
23c90 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
23ca0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
23cb0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
23cc0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
23cd0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
23ce0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
23cf0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
23d00 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
23d10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
23d20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
23d30 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
23d40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
23d50 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
23d60 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
23d70 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
23d80 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
23d90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
23db0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
23dc0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
23dd0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
23de0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
23df0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
23e00 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
23e10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23e20 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
23e30 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
23e40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
23e50 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
23e60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
23e70 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
23e80 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
23e90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
23ea0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
23eb0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
23ec0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
23ed0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
23ee0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
23ef0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
23f00 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
23f10 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
23f20 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23f30 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
23f40 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
23f50 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
23f60 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
23f70 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
23f80 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
23f90 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
23fa0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
23fb0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
23fc0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
23fd0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
23fe0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
23ff0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
24000 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
24010 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
24020 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
24030 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
24040 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
24050 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
24060 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
24070 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
24080 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
24090 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
240a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
240b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
240c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
240d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
240e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
240f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
24100 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
24110 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
24120 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
24130 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
24140 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
24150 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
24160 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
24170 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
24180 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
24190 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
241a0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
241b0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
241c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
241d0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
241e0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
241f0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
24200 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24210 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
24220 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24230 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24240 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24250 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
24260 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24270 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
24280 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
24290 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
242a0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
242b0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
242c0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
242d0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
242e0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
242f0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
24300 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
24310 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
24320 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
24330 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
24340 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
24350 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24360 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
24370 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24380 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24390 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
243a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
243b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
243c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
243d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
243e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
243f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24400 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24410 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24420 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24430 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24440 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
24460 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24470 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24480 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24490 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
244a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
244b0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
244c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
244d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
244e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
244f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
24500 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24510 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
24520 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
24530 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
24540 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
24550 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24560 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24570 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24580 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24590 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
245a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
245b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
245c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
245d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
245e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
245f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24600 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
24610 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
24620 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
24630 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
24640 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
24650 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
24660 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
24670 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
24680 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
24690 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
246a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
246b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
246c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
246d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
246e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
246f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24700 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
24710 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
24720 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
24730 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
24740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24750 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
24760 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
24770 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
24780 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
24790 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
247a0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
247b0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
247c0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
247d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
247e0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
247f0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
24800 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
24810 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
24820 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24840 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
24850 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
24860 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
24870 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24880 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24890 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
248a0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
248b0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
248c0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
248d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
248e0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
248f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24900 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24910 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
24920 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24930 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
24940 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
24950 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
24960 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24970 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
24980 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
24990 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
249a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
249b0 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
249c0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
249d0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
249e0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
249f0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
24a00 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
24a10 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
24a20 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
24a30 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
24a40 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
24a50 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
24a60 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
24a70 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
24a80 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
24a90 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
24aa0 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
24ab0 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
24ac0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
24ad0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
24ae0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
24af0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
24b00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
24b10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
24b20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
24b30 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
24b40 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
24b50 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24b60 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
24b70 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24b80 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
24b90 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
24ba0 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
24bb0 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
24bc0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
24bd0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
24be0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
24bf0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
24c00 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
24c10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
24c20 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
24c30 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
24c40 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
24c50 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
24c60 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
24c70 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
24c80 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
24c90 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
24ca0 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
24cb0 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
24cc0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
24cd0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
24ce0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
24cf0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
24d00 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
24d10 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24d20 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
24d30 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
24d40 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
24d50 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
24d60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
24d70 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
24d80 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
24d90 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
24da0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
24db0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
24dc0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
24dd0 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
24de0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
24df0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
24e00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24e10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24e20 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
24e30 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24e40 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
24e50 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
24e60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24e70 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
24e80 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
24e90 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
24ea0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24eb0 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
24ec0 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
24ed0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
24ee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
24ef0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
24f00 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
24f10 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
24f20 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
24f30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24f40 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
24f50 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
24f60 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
24f70 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
24f80 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
24f90 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
24fa0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
24fb0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
24fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24fd0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
24fe0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
24ff0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
25000 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
25010 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25020 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
25030 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
25040 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
25050 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
25060 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
25070 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
25080 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
25090 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
250a0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
250b0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
250c0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
250d0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
250e0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
250f0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
25100 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
25110 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
25120 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
25130 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
25140 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
25150 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
25160 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
25170 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25180 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
25190 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
251a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
251b0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
251c0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
251d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
251e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
251f0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
25200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
25210 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
25220 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
25230 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
25240 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
25250 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
25260 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
25270 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
25280 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
25290 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
252a0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
252b0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
252c0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
252d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
252e0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
252f0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
25300 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
25310 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
25320 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
25330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25340 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
25350 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
25360 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
25370 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
25380 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
25390 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
253a0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
253b0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
253c0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
253d0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
253e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
253f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
25400 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
25410 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
25420 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
25430 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
25440 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
25450 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
25460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25470 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
25480 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
25490 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
254a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
254b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
254c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
254d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
254e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
254f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25500 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25510 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
25520 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
25530 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25540 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25550 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
25560 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
25570 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
25580 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
25590 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
255a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
255b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
255c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
255d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
255e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
255f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
25600 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
25610 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
25620 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
25630 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
25640 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
25650 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
25660 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
25670 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25690 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
256a0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
256b0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
256c0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
256d0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
256e0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
256f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
25700 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
25710 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
25720 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
25730 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
25740 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
25750 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25760 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
25770 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
25780 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
25790 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
257a0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
257b0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
257c0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
257d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
257e0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
257f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25800 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
25810 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
25820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25830 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
25840 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
25850 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
25860 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
25870 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
25880 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25890 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
258a0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
258b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
258c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
258d0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
258e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
258f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
25900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
25910 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
25920 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
25930 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
25940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25950 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
25960 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
25970 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
25980 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
25990 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
259a0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
259b0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
259c0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
259d0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
259e0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
259f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
25a00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
25a10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
25a20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
25a30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
25a40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
25a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25a60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25a70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
25a80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
25a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
25aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
25ab0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
25ac0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
25ad0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
25ae0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
25af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
25b00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
25b10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
25b20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
25b30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
25b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
25b50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
25b60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25b70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
25b80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
25b90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
25ba0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
25bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
25bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
25bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
25be0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
25bf0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25c00 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
25c10 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
25c20 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
25c30 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
25c40 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
25c50 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
25c60 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
25c70 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
25c80 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
25c90 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
25ca0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
25cb0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
25cc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
25cd0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
25ce0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
25cf0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
25d00 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
25d10 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
25d20 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
25d30 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
25d40 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
25d50 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
25d60 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
25d70 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
25d80 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
25d90 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
25da0 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
25db0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
25dc0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
25dd0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
25de0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
25df0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
25e00 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
25e10 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
25e20 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
25e30 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
25e40 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
25e50 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
25e60 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
25e70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
25e80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
25e90 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
25ea0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
25eb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
25ec0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
25ed0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
25ee0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
25ef0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
25f00 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
25f10 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
25f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
25f30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
25f40 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
25f50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
25f60 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
25f70 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
25f80 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
25f90 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
25fa0 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
25fb0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
25fc0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
25fd0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
25fe0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
25ff0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
26000 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
26010 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
26020 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
26030 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
26040 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
26050 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
26060 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
26070 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
26080 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
26090 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
260a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
260b0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
260c0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
260d0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
260e0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
260f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
26100 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
26110 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
26120 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
26130 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
26140 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
26150 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
26160 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
26170 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
26180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
26190 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
261a0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
261b0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
261c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
261d0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
261e0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
261f0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
26200 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
26210 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26220 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
26230 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
26240 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
26250 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
26260 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
26270 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
26280 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
26290 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
262a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
262b0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
262c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
262d0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
262e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
262f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
26300 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
26310 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  or..** If a non-
26320 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
26330 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
26340 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
26350 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
26360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
26370 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
26380 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
26390 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
263a0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
263b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
263c0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
263d0 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
263e0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
263f0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
26400 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
26410 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
26420 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
26430 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
26440 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
26450 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
26460 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
26470 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
26480 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
26490 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
264a0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
264b0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
264c0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
264d0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
264e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
264f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
26500 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
26510 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
26520 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
26530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
26540 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
26550 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
26560 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
26570 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
26580 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
26590 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
265a0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
265b0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
265c0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
265d0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
265e0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
265f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
26600 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
26610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
26620 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
26630 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
26640 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
26650 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26660 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
26670 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
26680 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
26690 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
266a0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
266b0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
266c0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
266d0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
266e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
266f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
26700 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
26710 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
26720 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
26730 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
26740 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
26750 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
26760 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
26770 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
26780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
26790 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
267a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
267b0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
267c0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
267d0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
267e0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
267f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
26800 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
26810 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
26820 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
26830 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
26840 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
26850 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
26860 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
26870 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
26880 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
26890 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
268a0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
268b0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
268c0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
268d0 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
268e0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
268f0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
26900 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
26910 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
26920 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
26930 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
26940 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
26950 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
26960 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
26970 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
26980 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
26990 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
269a0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
269b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269c0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
269d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
269e0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
269f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
26a00 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
26a10 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
26a20 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
26a30 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
26a40 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
26a50 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
26a60 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
26a70 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
26a80 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
26a90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
26aa0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
26ab0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
26ac0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
26ad0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
26ae0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
26af0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
26b00 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
26b10 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
26b20 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
26b30 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
26b40 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
26b50 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
26b60 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
26b70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
26b80 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
26b90 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
26ba0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
26bb0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
26bc0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
26bd0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
26be0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
26bf0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
26c00 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
26c10 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
26c20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
26c30 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
26c40 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
26c50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
26c60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26c70 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
26c80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26c90 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
26ca0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
26cb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26cc0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
26cd0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26ce0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
26cf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26d00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
26d10 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
26d20 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
26d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26d40 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
26d50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
26d60 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
26d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26d80 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
26d90 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
26da0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26db0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
26dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26dd0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
26de0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
26df0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26e00 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
26e10 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
26e20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26e30 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
26e40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26e50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
26e60 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
26e70 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
26e80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26e90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
26ea0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
26eb0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
26ec0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
26ed0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
26ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26f00 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
26f10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
26f20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26f30 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
26f40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26f50 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
26f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
26f70 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
26f80 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
26f90 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
26fa0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
26fb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
26fc0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
26fd0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
26fe0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
26ff0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
27000 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
27010 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
27020 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
27030 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
27040 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
27050 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
27060 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
27070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27080 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
27090 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
270a0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
270b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
270c0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
270d0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
270e0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
270f0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
27100 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
27110 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
27120 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
27130 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
27140 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
27150 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
27160 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
27170 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
27180 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
27190 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
271a0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
271b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
271c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
271d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
271e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
271f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
27200 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
27210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27220 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27230 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27240 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
27250 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
27260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27280 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
27290 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
272a0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
272b0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
272c0 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
272d0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
272e0 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
272f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
27300 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
27310 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
27320 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
27330 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
27340 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
27350 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
27360 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
27370 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
27380 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
27390 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
273a0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
273b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
273c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
273d0 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
273e0 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
273f0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
27400 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
27410 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
27420 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
27430 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
27440 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
27450 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
27460 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
27470 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
27480 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
27490 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
274a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
274b0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
274c0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
274d0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
274e0 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
274f0 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
27500 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
27510 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
27520 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
27530 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
27540 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
27550 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
27560 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
27570 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
27580 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
27590 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
275a0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
275b0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
275c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
275d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
275e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
275f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
27600 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
27610 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
27620 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
27630 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27640 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
27650 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
27660 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
27670 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
27680 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
27690 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
276a0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
276b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
276c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
276d0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
276e0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
276f0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
27700 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
27710 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
27720 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
27730 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
27740 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
27750 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
27760 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
27770 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
27780 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
27790 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
277a0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
277b0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
277c0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
277d0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
277e0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
277f0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
27800 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
27810 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
27820 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
27830 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
27840 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
27850 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27860 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
27870 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27880 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27890 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
278a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
278b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
278c0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
278d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
278e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
278f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
27900 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
27910 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27920 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
27930 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
27940 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
27950 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
27960 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
27970 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27980 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
27990 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
279a0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
279b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
279c0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
279d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
279e0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
279f0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
27a00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
27a10 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
27a20 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
27a30 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
27a40 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
27a50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27a60 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
27a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
27a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27a90 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
27aa0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
27ab0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
27ac0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
27ad0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
27ae0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
27af0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
27b00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27b10 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
27b20 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
27b30 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
27b40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
27b50 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
27b60 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
27b70 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
27b80 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27b90 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
27ba0 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
27bb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27bc0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
27bd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
27be0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27bf0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
27c00 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
27c10 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
27c20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
27c30 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
27c40 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
27c50 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
27c60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
27c70 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
27c80 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
27c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
27ca0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
27cb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
27cc0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
27cd0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
27ce0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
27cf0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
27d00 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
27d10 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
27d20 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
27d30 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
27d40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27d50 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
27d60 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27d70 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
27d80 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
27d90 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
27da0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
27db0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
27dc0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
27dd0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
27de0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
27df0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
27e00 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
27e10 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
27e20 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
27e30 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
27e40 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
27e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27e60 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
27e70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
27e80 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
27e90 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
27ea0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
27eb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27ec0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
27ed0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
27ee0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
27ef0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
27f00 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
27f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
27f20 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
27f30 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
27f40 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
27f50 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
27f60 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
27f70 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
27f80 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
27f90 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
27fa0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
27fb0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
27fc0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
27fd0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
27fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
27ff0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
28000 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
28010 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
28020 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
28030 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
28040 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
28050 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
28060 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
28070 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
28080 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
28090 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
280a0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
280b0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
280c0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
280d0 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  xt..*/.SQLITE_AP
280e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
280f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
28100 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28110 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
28120 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
28130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
28140 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
28150 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
28160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
28170 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
28180 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
28190 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
281a0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
281b0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
281c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
281d0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
281e0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
281f0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
28200 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
28210 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
28220 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
28230 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
28240 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
28250 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
28260 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
28270 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
28280 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
28290 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
282a0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
282b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
282c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
282d0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
282e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
282f0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
28300 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
28310 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
28320 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
28330 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
28340 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
28350 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
28360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28370 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
28380 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
28390 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
283a0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
283b0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
283c0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
283d0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
283e0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
283f0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
28400 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
28410 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
28420 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
28430 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
28440 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
28450 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
28460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
28470 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
28480 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
28490 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
284a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
284b0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
284c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
284d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
284e0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
284f0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
28500 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
28510 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28520 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
28530 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
28540 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
28550 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
28560 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
28570 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
28580 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
28590 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
285a0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
285b0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
285c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
285d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
285e0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
285f0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
28600 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
28610 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
28620 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
28630 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
28640 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
28650 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
28660 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
28670 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
28680 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
28690 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
286a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
286b0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
286c0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
286d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
286e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
286f0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
28700 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
28710 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
28720 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
28730 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
28740 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
28750 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
28760 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
28770 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
28780 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
28790 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
287a0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
287b0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
287c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
287d0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
287e0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
287f0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
28800 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
28810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
28820 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
28830 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
28840 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
28850 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
28860 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
28870 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
28880 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
28890 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
288a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
288b0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
288c0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
288d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
288e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
288f0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
28900 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28910 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
28920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
28930 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
28940 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
28950 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
28960 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
28970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
28980 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
28990 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
289a0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
289b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
289c0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
289d0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
289e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
289f0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
28a00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
28a10 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28a20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28a30 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
28a40 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
28a50 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
28a60 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
28a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28a80 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
28a90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
28aa0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
28ab0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
28ac0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
28ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28ae0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28af0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
28b10 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
28b20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
28b30 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
28b40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28b50 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
28b60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28b80 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
28b90 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
28ba0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
28bb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28bc0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
28bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
28be0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
28bf0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
28c00 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
28c10 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28c20 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
28c30 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
28c40 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
28c50 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
28c60 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
28c70 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
28c80 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
28c90 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
28ca0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
28cb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
28cc0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
28cd0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
28ce0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
28cf0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28d00 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
28d10 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
28d20 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
28d30 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28d40 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
28d50 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
28d60 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
28d70 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
28d80 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
28d90 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
28da0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
28db0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
28dc0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
28dd0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
28de0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
28df0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
28e00 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
28e10 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
28e20 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
28e30 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
28e40 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
28e50 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
28e60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
28e70 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
28e80 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
28e90 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
28ea0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
28eb0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
28ec0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
28ed0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
28ee0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
28ef0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
28f00 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
28f10 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
28f20 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
28f30 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
28f40 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
28f50 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
28f60 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
28f70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
28f80 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
28f90 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
28fa0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
28fb0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
28fc0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
28fd0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
28fe0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
28ff0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
29000 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
29010 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29020 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
29030 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29040 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
29050 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
29060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
29070 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
29080 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
29090 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
290a0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
290b0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
290c0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
290d0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
290e0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
290f0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
29100 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29110 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
29120 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
29130 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
29140 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
29150 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29160 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
29170 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
29180 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
29190 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
291a0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
291b0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
291c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
291d0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
291e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
291f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
29200 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
29210 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
29220 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
29230 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
29240 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
29250 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
29260 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29270 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
29280 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29290 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
292a0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
292b0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
292c0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
292d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
292e0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
292f0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
29300 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
29310 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
29320 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
29330 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
29340 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
29350 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
29360 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
29370 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
29380 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
29390 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
293a0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
293b0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
293c0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
293d0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
293e0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
293f0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
29400 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
29410 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
29420 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
29430 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
29440 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
29450 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
29460 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
29470 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
29480 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
29490 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
294a0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
294b0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
294c0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
294d0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
294e0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
294f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29500 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
29510 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
29520 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
29530 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
29540 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
29550 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
29560 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
29570 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
29580 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
29590 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
295a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
295b0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
295c0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
295d0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
295e0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
295f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
29600 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
29610 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
29620 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
29630 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
29640 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
29650 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
29660 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29670 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
29680 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
29690 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
296a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
296b0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
296c0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
296d0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
296e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
296f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
29700 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
29710 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
29720 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
29730 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
29740 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
29750 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
29760 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
29770 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
29780 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
29790 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
297a0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
297b0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
297c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
297d0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
297e0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
297f0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
29800 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
29810 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
29820 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
29830 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
29840 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
29850 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
29860 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
29870 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
29880 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
29890 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
298a0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
298b0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
298c0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
298d0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
298e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
298f0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
29900 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29910 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
29920 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
29930 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
29940 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
29950 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
29960 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
29970 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
29980 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
29990 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
299a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
299b0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
299c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
299d0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
299e0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
299f0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
29a00 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
29a10 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
29a20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
29a30 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
29a40 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
29a50 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
29a60 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
29a70 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
29a80 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
29a90 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
29aa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ab0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
29ac0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
29ad0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
29ae0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
29af0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
29b00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
29b10 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
29b20 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
29b30 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
29b40 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
29b50 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
29b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29b70 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
29b80 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
29b90 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
29ba0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
29bb0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
29bc0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
29bd0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
29be0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
29bf0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
29c00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
29c10 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
29c20 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
29c30 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
29c40 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
29c50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
29c60 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
29c70 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
29c80 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
29c90 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
29ca0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
29cb0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29cc0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
29cd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29ce0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
29cf0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
29d00 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
29d10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
29d20 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
29d30 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
29d40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29d50 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
29d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29d70 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
29d80 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
29d90 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
29da0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
29db0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29dc0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
29dd0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
29de0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
29df0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
29e00 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
29e10 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
29e20 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
29e30 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
29e40 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
29e50 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
29e60 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
29e70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
29e80 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
29e90 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
29ea0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
29eb0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
29ec0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
29ed0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
29ee0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
29ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
29f00 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
29f10 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
29f20 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
29f30 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
29f40 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
29f50 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
29f60 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
29f70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29f80 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
29f90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
29fa0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29fb0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
29fc0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
29fd0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
29fe0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
29ff0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2a000 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2a010 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2a020 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2a030 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2a040 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2a050 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2a060 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a070 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2a080 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2a090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2a0a0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2a0b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a0c0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2a0d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a0e0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2a0f0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2a100 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2a110 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2a120 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2a130 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2a140 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2a150 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2a160 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2a170 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2a180 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2a190 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2a1a0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2a1b0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
2a1c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a1d0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2a1e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2a1f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2a200 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2a210 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2a220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2a230 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2a240 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2a250 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a260 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2a270 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2a280 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2a290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a2a0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2a2b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a2c0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2a2d0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2a2e0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2a2f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2a300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a310 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2a320 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2a330 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2a340 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a350 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2a360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2a370 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2a380 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2a390 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2a3a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2a3b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2a3c0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2a3d0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2a3e0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2a3f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2a400 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2a410 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2a420 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2a430 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2a440 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2a450 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2a460 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a470 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2a480 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2a490 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2a4a0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2a4b0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2a4c0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2a4d0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2a4e0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2a4f0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2a500 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2a510 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2a520 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2a530 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2a540 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2a550 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
2a560 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a570 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2a590 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2a5a0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2a5b0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2a5c0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2a5d0 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2a5e0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2a5f0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2a600 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2a610 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2a620 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2a630 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2a640 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2a650 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2a660 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2a670 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2a680 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2a690 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2a6a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2a6b0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2a6c0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2a6d0 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2a6e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2a6f0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2a700 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2a710 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2a720 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2a730 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2a740 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2a750 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2a760 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2a770 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2a780 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2a790 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2a7a0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2a7b0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2a7c0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2a7d0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2a7e0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2a7f0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2a800 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2a810 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2a820 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2a830 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2a840 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2a850 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2a860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2a870 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2a880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2a890 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2a8a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2a8b0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2a8c0 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2a8d0 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2a8e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2a8f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a900 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2a910 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2a920 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2a930 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a940 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a950 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2a960 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2a970 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2a980 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2a990 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2a9a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2a9b0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2a9c0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2a9d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2a9e0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2a9f0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2aa00 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2aa10 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2aa20 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2aa30 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2aa40 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2aa50 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2aa60 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2aa70 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2aa80 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2aa90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2aaa0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2aab0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2aac0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2aad0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2aae0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2aaf0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2ab00 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2ab10 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2ab20 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2ab30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2ab40 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2ab50 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2ab60 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2ab70 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2ab80 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2ab90 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2aba0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2abb0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2abc0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2abd0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2abe0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2abf0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2ac00 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2ac10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2ac20 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2ac30 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2ac40 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2ac50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ac60 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2ac70 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2ac80 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2ac90 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2aca0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2acb0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2acc0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2acd0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2ace0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2acf0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2ad00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ad10 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2ad20 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2ad30 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2ad40 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2ad50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2ad60 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2ad70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2ad80 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2ad90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2ada0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2adb0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2adc0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2add0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2ade0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2adf0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2ae00 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ae10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ae20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ae30 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2ae40 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2ae50 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2ae60 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2ae70 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2ae80 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2ae90 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2aea0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2aeb0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2aec0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2aed0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2aee0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2aef0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2af00 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2af10 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2af20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2af30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2af40 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2af50 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2af60 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2af70 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2af80 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2af90 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2afa0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2afb0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2afc0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2afd0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2afe0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2aff0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2b000 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2b010 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2b020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b030 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2b040 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2b050 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2b060 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2b070 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2b080 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2b090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b0a0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2b0b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2b0c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2b0d0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2b0e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2b0f0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2b100 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2b110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b120 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2b130 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2b140 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2b150 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2b160 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2b170 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2b180 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2b190 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2b1a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2b1b0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2b1c0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2b1d0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2b1e0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2b1f0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2b200 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2b210 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2b220 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2b230 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2b240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b250 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2b260 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2b270 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2b280 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2b290 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2b2a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2b2b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2b2c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b2d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2b2e0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2b2f0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2b300 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b310 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2b320 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b330 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2b340 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2b350 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2b360 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2b370 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2b380 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2b390 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2b3a0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2b3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b3c0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2b3d0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2b3e0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2b3f0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2b400 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2b410 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2b420 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b430 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2b440 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2b450 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2b460 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2b470 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2b480 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2b490 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2b4a0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2b4b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2b4c0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2b4d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b4e0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2b4f0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2b500 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2b510 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2b520 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2b530 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2b540 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2b550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b560 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2b570 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b580 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2b590 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2b5a0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2b5b0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2b5c0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2b5d0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2b5e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2b5f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2b600 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b610 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2b620 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2b630 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2b640 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2b650 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2b660 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2b670 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2b680 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2b690 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2b6a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2b6b0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2b6c0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2b6d0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2b6e0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2b6f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b700 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2b710 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2b720 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b730 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2b740 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2b750 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2b760 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2b770 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2b780 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2b790 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b7a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2b7b0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b7d0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2b7e0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2b7f0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2b800 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2b810 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2b820 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2b830 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2b840 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2b850 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2b860 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2b870 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2b880 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2b890 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2b8a0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2b8b0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2b8c0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2b8d0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2b8e0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2b8f0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2b900 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2b910 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2b920 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2b930 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2b940 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2b950 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2b960 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2b970 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2b980 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2b990 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2b9a0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2b9b0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2b9c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2b9d0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2b9e0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2b9f0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2ba00 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2ba10 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2ba20 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2ba30 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2ba40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2ba50 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2ba60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2ba70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2ba80 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2ba90 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2baa0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2bab0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2bac0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2bad0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2bae0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2baf0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2bb00 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2bb10 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2bb20 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2bb30 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2bb40 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2bb50 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2bb60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2bb70 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2bb80 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2bb90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2bba0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2bbb0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2bbc0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2bbd0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2bbe0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2bbf0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2bc00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2bc10 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
2bc20 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
2bc30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2bc40 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2bc50 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2bc60 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2bc70 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2bc80 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2bc90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2bca0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
2bcb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2bcc0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
2bcd0 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
2bce0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2bcf0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2bd00 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
2bd10 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2bd20 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2bd30 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2bd40 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2bd50 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2bd60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2bd70 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2bd80 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2bd90 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2bda0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2bdb0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2bdc0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2bdd0 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
2bde0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2bdf0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2be00 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2be10 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2be20 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2be30 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2be40 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2be50 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2be60 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2be70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2be80 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2be90 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2bea0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2beb0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2bec0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2bed0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2bee0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2bef0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2bf00 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2bf10 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2bf20 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2bf30 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2bf40 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2bf50 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2bf60 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2bf70 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2bf80 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2bf90 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2bfa0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2bfb0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2bfc0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2bfd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bfe0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2bff0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2c000 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2c010 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2c020 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2c030 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2c040 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2c050 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2c060 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2c070 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2c080 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2c090 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2c0a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2c0b0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2c0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2c0d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2c0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c0f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2c100 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2c110 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2c120 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2c130 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2c140 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2c150 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2c160 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2c170 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2c180 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2c190 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2c1a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2c1b0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2c1c0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2c1d0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2c1e0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2c1f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2c200 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2c210 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2c220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c230 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2c240 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2c250 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2c260 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2c270 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2c280 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2c290 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2c2a0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2c2b0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2c2c0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2c2d0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2c2e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2c2f0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2c300 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2c310 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2c320 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2c330 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2c340 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2c350 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2c360 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2c370 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2c380 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2c390 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2c3a0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2c3b0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2c3c0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2c3d0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2c3e0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2c3f0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2c400 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2c410 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2c420 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2c430 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2c440 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2c450 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2c460 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2c470 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2c480 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2c490 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2c4a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c4b0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2c4c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c4d0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2c4e0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c4f0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2c500 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c510 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2c520 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2c530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c540 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2c550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c560 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2c570 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2c580 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2c590 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2c5a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2c5b0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2c5c0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2c5d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c5e0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2c5f0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2c600 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2c610 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2c620 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2c630 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2c640 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2c650 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2c660 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2c670 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2c680 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2c690 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2c6a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2c6b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c6c0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2c6d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2c6e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2c6f0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2c700 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2c710 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c720 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2c730 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2c740 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2c750 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2c760 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2c770 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2c780 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2c790 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2c7a0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2c7b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c7c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2c7d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2c7e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c7f0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2c800 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2c810 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2c820 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2c830 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2c840 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2c850 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2c860 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2c870 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
2c880 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2c890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c8a0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2c8b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2c8c0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2c8d0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2c8e0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2c8f0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2c900 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2c910 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2c920 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2c930 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2c940 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2c950 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2c960 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2c970 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2c980 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2c990 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2c9a0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2c9b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2c9c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2c9d0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2c9e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2c9f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2ca00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ca10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2ca20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ca30 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ca40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ca50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2ca60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ca70 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2ca80 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2ca90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2caa0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cab0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2cac0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
2cad0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
2cae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2caf0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2cb00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2cb10 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2cb20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2cb30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2cb40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2cb50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2cb60 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2cb70 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2cb80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
2cb90 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2cba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cbb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cbc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2cbd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2cbe0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cbf0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2cc00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2cc10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2cc20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cc30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2cc40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2cc50 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2cc60 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
2cc70 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
2cc80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2cc90 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
2cca0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
2ccb0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ccc0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2ccd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cce0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
2ccf0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2cd00 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
2cd10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2cd20 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2cd30 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2cd40 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
2cd50 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
2cd60 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
2cd70 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2cd80 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
2cd90 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
2cda0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2cdb0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
2cdc0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
2cdd0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2cde0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
2cdf0 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
2ce00 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
2ce10 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
2ce20 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
2ce30 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
2ce40 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
2ce50 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2ce60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2ce70 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
2ce80 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
2ce90 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
2cea0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
2ceb0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
2cec0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ced0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
2cee0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
2cef0 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
2cf00 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
2cf10 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2cf20 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
2cf30 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
2cf40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2cf50 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
2cf60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
2cf70 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2cf80 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
2cf90 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
2cfa0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
2cfb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
2cfc0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2cfd0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
2cfe0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
2cff0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
2d000 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
2d010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d020 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
2d030 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
2d040 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
2d050 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
2d060 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2d070 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
2d080 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
2d090 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
2d0a0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2d0b0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
2d0c0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
2d0d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
2d0e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2d0f0 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
2d100 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
2d110 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
2d120 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
2d130 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
2d140 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
2d150 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
2d160 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  I int sqlite3_fi
2d170 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2d180 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2d1a0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2d1b0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2d1c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d1d0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2d1e0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2d1f0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2d200 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d210 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2d220 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d230 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2d240 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2d250 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2d260 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2d270 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2d280 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2d290 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2d2a0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2d2b0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2d2c0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2d2d0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2d2e0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2d2f0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2d300 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2d310 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2d320 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2d330 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2d340 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d350 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2d360 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2d370 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2d380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d390 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2d3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2d3b0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2d3c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d3d0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2d3e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2d3f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2d400 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2d410 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2d420 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2d430 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2d440 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2d450 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d460 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2d470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2d480 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2d490 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2d4a0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2d4b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d4c0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2d4d0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2d4e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d4f0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2d500 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2d510 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2d520 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2d530 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2d540 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2d550 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2d560 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2d570 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2d580 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2d590 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2d5a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2d5b0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2d5c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d5d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d5e0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2d5f0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2d600 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2d610 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2d620 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2d630 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2d640 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2d650 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d660 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2d670 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2d680 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d690 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2d6a0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2d6b0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2d6c0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2d6d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2d6e0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2d6f0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2d700 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2d710 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2d720 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2d730 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2d740 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2d750 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2d760 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2d770 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2d780 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2d790 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2d7a0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2d7b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2d7c0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2d7d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2d7e0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2d7f0 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2d800 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2d810 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2d820 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2d830 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2d840 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2d850 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2d860 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2d870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2d880 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2d890 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2d8a0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2d8b0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2d8c0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2d8d0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2d8e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2d8f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d900 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d910 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2d920 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2d930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2d940 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2d950 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2d960 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2d970 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2d980 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2d990 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2d9a0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2d9b0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2d9c0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2d9d0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2d9e0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2d9f0 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2da00 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2da10 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2da20 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2da30 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2da40 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2da50 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2da60 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2da70 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2da80 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2da90 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2daa0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2dab0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2dac0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2dad0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2dae0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2daf0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2db00 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2db10 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2db20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2db30 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2db40 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2db50 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2db60 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2db70 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2db80 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2db90 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2dba0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2dbb0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2dbc0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2dbd0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2dbe0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2dbf0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2dc00 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2dc10 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2dc20 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2dc30 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2dc40 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2dc50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2dc60 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2dc70 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2dc80 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2dc90 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2dca0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2dcb0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2dcc0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2dcd0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2dce0 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2dcf0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2dd00 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2dd10 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2dd20 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2dd30 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2dd40 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2dd50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2dd60 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2dd70 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2dd80 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2dd90 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2dda0 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2ddb0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2ddc0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2ddd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2dde0 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2ddf0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2de00 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2de10 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2de20 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2de30 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2de40 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2de50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2de60 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2de70 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2de80 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2de90 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2dea0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2deb0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2dec0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2ded0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2dee0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2def0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2df00 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2df10 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2df20 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2df30 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2df40 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2df50 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2df60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2df70 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2df80 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2df90 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2dfa0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2dfb0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2dfc0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2dfd0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2dfe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2dff0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2e000 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2e010 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2e020 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2e030 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2e040 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2e050 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2e060 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2e070 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2e080 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2e090 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2e0a0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2e0b0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2e0c0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2e0d0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2e0e0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2e0f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2e100 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2e110 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2e120 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2e130 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2e140 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2e150 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2e160 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2e170 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2e180 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2e190 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2e1a0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2e1b0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2e1c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2e1d0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2e1e0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2e1f0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2e200 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2e210 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2e220 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2e230 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2e240 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e250 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2e260 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2e270 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2e280 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2e290 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2e2a0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2e2b0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2e2c0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2e2d0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2e2e0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2e2f0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2e300 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2e310 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2e320 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2e330 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2e340 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2e350 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2e360 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e370 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2e380 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2e390 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2e3a0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2e3b0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2e3c0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2e3d0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2e3e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2e3f0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2e400 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2e410 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2e420 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2e430 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2e440 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e450 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2e460 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2e470 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2e480 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2e490 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2e4a0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2e4b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2e4c0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2e4d0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2e4e0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2e4f0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2e500 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2e510 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2e520 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2e530 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e540 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2e550 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2e560 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2e570 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2e580 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2e590 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2e5a0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2e5b0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2e5c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2e5d0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2e5e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2e5f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2e600 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2e610 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2e620 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2e630 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2e640 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2e650 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2e660 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2e670 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2e680 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2e690 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2e6a0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2e6b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e6c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e6d0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2e6e0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2e6f0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2e700 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2e710 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2e720 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e730 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2e740 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2e750 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2e760 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2e770 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2e780 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2e790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e7a0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2e7b0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2e7c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2e7d0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2e7e0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2e7f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2e800 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2e810 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2e820 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2e830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e840 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2e850 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2e860 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2e870 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2e880 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2e890 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2e8a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
2e8b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2e8c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2e8d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2e8e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2e8f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2e900 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2e910 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2e920 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2e930 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e940 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e950 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2e960 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2e970 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2e980 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2e990 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2e9a0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
2e9b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e9c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2e9d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2e9e0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2e9f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2ea00 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2ea10 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2ea20 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2ea30 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2ea40 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2ea50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2ea60 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2ea70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ea80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2ea90 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2eaa0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2eab0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
2eac0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ead0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2eae0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2eaf0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2eb00 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2eb10 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2eb20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2eb30 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2eb40 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2eb50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2eb60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2eb70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2eb80 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2eb90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2eba0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2ebb0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2ebc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2ebd0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2ebe0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2ebf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2ec00 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2ec10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2ec20 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2ec30 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2ec40 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2ec50 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2ec60 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2ec70 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2ec80 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2ec90 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2eca0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2ecb0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2ecc0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2ecd0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2ece0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2ecf0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2ed00 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2ed10 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2ed20 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2ed30 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2ed40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ed50 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2ed60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2ed70 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2ed80 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2ed90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2eda0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2edb0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2edc0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2edd0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2ede0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2edf0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2ee00 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2ee10 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2ee20 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2ee30 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2ee40 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2ee50 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2ee60 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2ee70 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2ee80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2ee90 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2eea0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2eeb0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2eec0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2eed0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2eee0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2eef0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2ef00 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2ef10 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2ef20 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2ef30 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2ef40 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  TED.SQLITE_API S
2ef50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ef60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2ef70 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2ef80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2ef90 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2efa0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2efb0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
2efc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2efd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2efe0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2eff0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2f000 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2f010 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2f020 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f030 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2f040 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f050 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2f060 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2f070 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2f080 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
2f090 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2f0a0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
2f0b0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2f0c0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f0d0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2f0e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2f0f0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2f100 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2f110 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
2f120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f130 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2f140 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2f150 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
2f160 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2f170 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2f180 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2f190 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2f1a0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2f1b0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2f1c0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2f1d0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2f1e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2f1f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2f200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2f210 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2f220 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2f230 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2f240 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2f250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2f260 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2f270 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2f280 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2f290 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2f2a0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2f2b0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2f2c0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2f2d0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
2f2e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2f2f0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2f300 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2f310 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2f320 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f330 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2f340 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2f350 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f360 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2f370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f380 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2f390 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f3a0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2f3b0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2f3c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2f3d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2f3e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f3f0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2f400 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2f410 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f420 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2f430 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2f440 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2f450 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2f460 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2f470 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2f480 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2f490 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
2f4a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2f4b0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2f4c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2f4d0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2f4e0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2f4f0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2f500 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2f510 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2f520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f530 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2f540 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2f550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2f560 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2f570 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2f580 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2f590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f5a0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2f5b0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2f5c0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2f5d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2f5e0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2f5f0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
2f600 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2f610 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2f620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f630 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2f640 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2f650 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2f660 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2f670 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2f680 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2f690 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
2f6a0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2f6b0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2f6c0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2f6d0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2f6e0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2f6f0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2f700 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2f710 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2f720 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2f730 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2f740 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2f750 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2f760 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2f770 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2f780 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2f790 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2f7a0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2f7b0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2f7c0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2f7d0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2f7e0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2f7f0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2f800 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2f810 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2f820 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2f830 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2f840 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2f850 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2f860 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2f870 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2f880 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2f890 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2f8a0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2f8b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2f8c0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2f8d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f8e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2f8f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f900 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2f910 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2f920 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2f930 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2f940 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2f950 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2f960 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2f970 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2f980 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2f990 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2f9a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f9b0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2f9c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f9d0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2f9e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2f9f0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2fa00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2fa10 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
2fa20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2fa30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2fa40 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
2fa50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2fa60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2fa70 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
2fa80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2fa90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2faa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2fab0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
2fac0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2fad0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
2fae0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
2faf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2fb00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2fb10 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2fb20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2fb30 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2fb40 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2fb50 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
2fb60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2fb70 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
2fb80 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2fb90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2fba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2fbb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fbc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2fbd0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2fbe0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2fbf0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2fc00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2fc10 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2fc20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2fc30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2fc40 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2fc50 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2fc60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2fc70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fc80 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2fc90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2fca0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2fcb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2fcc0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
2fcd0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
2fce0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2fcf0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
2fd00 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
2fd10 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
2fd20 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
2fd30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
2fd40 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
2fd50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
2fd60 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
2fd70 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
2fd80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
2fd90 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
2fda0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fdb0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
2fdc0 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
2fdd0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
2fde0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2fdf0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
2fe00 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
2fe10 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
2fe20 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
2fe30 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2fe40 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
2fe50 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
2fe60 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2fe70 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2fe80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2fe90 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
2fea0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2feb0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2fec0 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
2fed0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
2fee0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
2fef0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2ff00 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
2ff10 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
2ff20 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
2ff30 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
2ff40 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
2ff50 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
2ff60 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
2ff70 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
2ff80 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
2ff90 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
2ffa0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
2ffb0 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
2ffc0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
2ffd0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
2ffe0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2fff0 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
30000 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
30010 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
30020 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
30030 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
30040 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30050 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
30060 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
30070 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
30080 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
30090 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
300a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
300b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
300c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
300d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
300e0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
300f0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
30100 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
30110 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  y allocate error
30120 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
30130 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
30140 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
30150 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
30160 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
30170 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
30180 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
30190 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
301a0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
301b0 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
301c0 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
301d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
301e0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
301f0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
30200 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
30210 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
30220 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
30230 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
30240 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
30250 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  tion.)^.**.** ^S
30260 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
30270 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
30280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
30290 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
302a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
302b0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
302c0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
302d0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
302e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
302f0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
30300 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
30310 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
30320 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
30330 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
30340 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
30350 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
30360 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
30370 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
30380 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
30390 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
303a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
303b0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
303c0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
303d0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
303e0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
303f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30400 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
30410 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
30420 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
30430 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
30440 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30450 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
30460 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
30470 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
30480 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
30490 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
304a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
304b0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
304c0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
304d0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
304e0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
304f0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
30500 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
30510 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30520 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
30530 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30540 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
30550 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
30560 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
30570 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
30580 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
30590 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
305a0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
305b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
305c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
305d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
305e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
305f0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
30600 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
30610 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
30620 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
30630 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30650 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
30660 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
30670 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
30680 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
30690 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
306a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
306b0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
306c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
306d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
306e0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
306f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
30700 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30710 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
30720 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
30730 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
30740 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
30750 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
30760 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
30770 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
30780 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
30790 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
307a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
307b0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
307c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
307d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
307e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
307f0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
30800 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
30810 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
30820 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
30830 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
30840 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
30850 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
30860 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
30870 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
30880 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
30890 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
308a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
308b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
308c0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
308d0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
308e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
308f0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
30900 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
30910 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
30920 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
30930 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
30940 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
30950 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
30960 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
30970 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
30980 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
30990 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
309a0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
309b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
309c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
309d0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
309e0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
309f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
30a00 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
30a10 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
30a20 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
30a30 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
30a40 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
30a50 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
30a60 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
30a70 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
30a80 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
30a90 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30aa0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
30ab0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
30ac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30ad0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
30ae0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30af0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
30b00 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
30b10 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
30b20 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
30b30 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
30b40 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
30b50 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
30b60 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
30b70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30b80 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74  tion. ^If no met
30b90 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
30ba0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
30bb0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
30bc0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
30bd0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
30be0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
30bf0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
30c00 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
30c10 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
30c20 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
30c30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
30c40 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
30c50 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
30c60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30c70 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30c80 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
30c90 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
30ca0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
30cb0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
30cc0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
30cd0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
30ce0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
30cf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30d00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30d10 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
30d20 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
30d30 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
30d40 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
30d50 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
30d60 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
30d70 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20  stroyed..** ^If 
30d80 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
30d90 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
30da0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
30db0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
30dc0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
30dd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30de0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30df0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
30e00 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
30e10 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
30e20 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
30e30 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
30e40 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
30e50 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
30e60 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
30e70 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
30e80 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
30e90 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
30ea0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
30eb0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
30ec0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
30ed0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
30ee0 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20  ime.  ^The only 
30ef0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
30f00 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
30f10 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
30f20 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
30f30 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
30f40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
30f50 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
30f60 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
30f70 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
30f80 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
30f90 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
30fa0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
30fb0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
30fc0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
30fd0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
30fe0 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a  parameters].)^.*
30ff0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
31000 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
31010 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
31020 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
31030 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
31040 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
31050 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
31060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
31070 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
31080 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
31090 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
310a0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
310b0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
310c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
310d0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
310e0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
310f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
31100 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
31110 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
31120 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
31130 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
31140 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
31150 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
31160 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
31170 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
31180 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
31190 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
311a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
311b0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
311c0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
311d0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
311e0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
311f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
31200 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
31210 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
31220 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
31230 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
31240 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
31250 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
31260 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
31270 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
31280 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
31290 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
312a0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
312b0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
312c0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
312d0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
312e0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
312f0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
31300 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
31310 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
31320 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
31330 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
31340 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
31350 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
31360 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
31370 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
31380 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
31390 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
313a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
313b0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
313c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
313d0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
313e0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
313f0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
31400 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
31410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
31420 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
31430 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
31440 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
31450 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
31460 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
31470 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
31480 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
31490 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
314a0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
314b0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
314c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
314d0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
314e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
314f0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
31500 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
31510 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
31520 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
31530 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
31540 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
31550 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
31560 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
31570 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
31580 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
31590 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
315a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
315b0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
315c0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
315d0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
315e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
315f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
31600 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31610 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
31620 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31630 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
31640 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31650 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
31660 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
31670 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
31680 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
31690 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
316a0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
316b0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
316c0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
316d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
316e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
316f0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
31700 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
31710 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
31720 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
31730 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31740 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
31750 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
31760 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
31770 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
31780 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
31790 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
317a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
317b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
317c0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
317d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
317e0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
317f0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
31800 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31810 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
31820 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
31830 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
31840 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
31850 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
31860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31870 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
31880 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31890 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
318a0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
318b0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
318c0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
318d0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
318e0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
318f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
31900 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
31910 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
31920 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31930 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
31940 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
31950 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
31960 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
31970 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
31980 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
31990 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
319a0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
319b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
319c0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
319d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
319e0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
319f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31a00 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
31a10 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
31a20 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
31a30 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
31a40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
31a50 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
31a60 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31a70 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
31a80 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31a90 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
31aa0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
31ab0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
31ac0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
31ad0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
31ae0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
31af0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
31b00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31b10 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
31b20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31b30 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
31b40 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
31b50 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
31b60 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
31b70 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
31b80 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31b90 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
31ba0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
31bb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31bc0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
31bd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31be0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
31bf0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
31c00 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
31c10 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
31c20 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
31c30 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
31c40 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
31c50 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
31c60 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
31c70 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
31c80 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
31c90 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
31ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31cb0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
31cc0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
31cd0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
31ce0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
31cf0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
31d00 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
31d10 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
31d20 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
31d30 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
31d40 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
31d50 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
31d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31d70 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
31d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31d90 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
31da0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
31db0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
31dc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31dd0 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
31de0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31df0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31e00 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
31e10 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
31e20 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
31e30 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
31e40 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
31e50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31e60 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
31e70 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
31e80 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
31e90 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
31ea0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
31eb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
31ec0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
31ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31ee0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31ef0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31f00 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31f10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31f20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31f30 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
31f40 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31f50 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31f60 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31f80 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
31f90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
31fa0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
31fb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31fc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31fd0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
31fe0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
31ff0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
32000 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
32010 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32030 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
32040 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
32050 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
32060 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32070 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32080 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32090 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
320a0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
320b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
320c0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
320d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
320e0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
320f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
32100 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
32110 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
32120 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
32130 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32140 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
32150 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
32160 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
32170 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
32180 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
32190 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
321a0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
321b0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
321c0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
321d0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
321e0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
321f0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
32200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
32210 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
32220 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
32230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32240 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
32250 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
32260 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32280 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32290 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
322a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
322b0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
322c0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
322d0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
322e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
322f0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
32300 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
32310 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32320 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32330 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
32340 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
32350 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
32360 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
32370 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
32380 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32390 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
323a0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
323b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
323c0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
323d0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
323e0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
323f0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
32400 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
32410 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
32420 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
32430 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
32440 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
32450 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
32460 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
32470 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
32480 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
32490 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
324a0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
324b0 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
324c0 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
324d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
324e0 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
324f0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
32500 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
32510 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
32520 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
32530 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
32540 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
32550 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
32560 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
32570 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
32580 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
32590 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
325a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
325b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
325c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
325d0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
325e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
325f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
32600 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
32610 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
32620 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
32630 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
32640 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
32650 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
32660 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
32670 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
32680 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32690 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
326a0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
326b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
326c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
326d0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
326e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
326f0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
32700 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
32710 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
32720 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
32730 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
32740 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
32750 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
32760 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
32770 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
32780 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
32790 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
327a0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
327b0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
327c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
327d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
327e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
327f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
32800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32810 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
32820 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
32830 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
32840 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
32850 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
32860 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
32870 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
32880 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
32890 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
328a0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
328b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
328c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
328d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
328e0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
328f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32900 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32910 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
32920 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
32930 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32940 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
32950 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
32960 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
32970 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32980 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
32990 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
329a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
329b0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
329c0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
329d0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
329e0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
329f0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
32a00 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
32a10 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
32a20 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
32a30 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
32a40 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
32a50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32a60 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
32a70 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
32a80 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
32a90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32aa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
32ab0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
32ac0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
32ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32ae0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
32af0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
32b00 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
32b10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32b20 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
32b30 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
32b40 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
32b50 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
32b60 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
32b70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32b80 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
32b90 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
32ba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
32bb0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
32bc0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32bd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32be0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32bf0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
32c00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32c10 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
32c20 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
32c30 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32c40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
32c50 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
32c60 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53  ext*, double);.S
32c70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32c90 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
32ca0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
32cb0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
32cc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
32cd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32ce0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32cf0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32d00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32d10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32d20 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
32d30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32d40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
32d50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32d60 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
32d70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32d80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
32d90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32da0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
32db0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32dc0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
32dd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32de0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
32df0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53  ontext*, int);.S
32e00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32e10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32e20 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
32e30 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
32e40 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
32e50 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32e60 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
32e70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
32e80 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
32e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32ea0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32eb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
32ec0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32ed0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
32ee0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32ef0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
32f00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32f10 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
32f20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32f30 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32f50 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32f60 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32f70 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
32f80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
32f90 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
32fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32fb0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
32fc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32fd0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
32fe0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
32ff0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33000 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
33010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33030 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
33040 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33050 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33060 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33080 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33090 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
330a0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
330b0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
330c0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
330d0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
330e0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
330f0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
33100 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
33110 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
33120 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
33130 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33140 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
33150 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
33160 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
33170 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33180 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
33190 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
331a0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
331b0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
331c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
331d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
331e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
331f0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
33200 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
33210 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
33220 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
33230 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
33240 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
33250 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
33260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
33270 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
33280 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
33290 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
332a0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
332b0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
332c0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
332d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
332e0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
332f0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
33300 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
33310 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
33320 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
33330 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
33340 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
33350 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
33360 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
33370 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
33380 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
33390 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
333a0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
333b0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
333c0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
333d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
333e0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
333f0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
33400 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
33410 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
33420 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
33430 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
33440 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
33450 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
33460 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
33470 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
33480 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
33490 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
334a0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
334b0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
334c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
334d0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
334e0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
334f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
33500 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
33510 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33520 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33530 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
33540 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
33550 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33560 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33570 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
33580 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
33590 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
335a0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
335b0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
335c0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
335d0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
335e0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
335f0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
33600 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
33610 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
33620 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
33630 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
33640 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
33650 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
33660 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
33670 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33680 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
33690 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
336a0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
336b0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
336c0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
336d0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
336e0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
336f0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
33700 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
33710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
33720 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33730 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
33740 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
33750 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33760 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
33770 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
33780 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
33790 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
337a0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
337b0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
337c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
337d0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
337e0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
337f0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
33800 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
33810 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
33820 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
33830 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
33840 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
33850 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
33860 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
33870 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
33880 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
33890 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
338a0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
338b0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
338c0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
338d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
338e0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
338f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
33900 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
33910 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
33920 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
33930 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
33940 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
33950 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
33960 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
33970 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
33980 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33990 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
339a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
339b0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
339c0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
339d0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
339e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
339f0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
33a00 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
33a10 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
33a20 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
33a30 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
33a40 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
33a50 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
33a60 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
33a70 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
33a80 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33a90 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
33aa0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
33ab0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
33ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33ad0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
33ae0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
33af0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
33b00 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
33b10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
33b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
33b30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33b40 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
33b50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33b60 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
33b70 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
33b80 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
33b90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33ba0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
33bb0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
33bc0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
33bd0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
33be0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
33bf0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
33c00 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
33c10 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
33c20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
33c30 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
33c40 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
33c50 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
33c60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
33c70 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
33c80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
33c90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
33ca0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33cb0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
33cc0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
33cd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33ce0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
33cf0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
33d00 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
33d10 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
33d20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33d30 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
33d40 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
33d50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
33d60 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
33d70 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
33d80 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
33d90 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33da0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
33db0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
33dc0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
33dd0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
33de0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
33df0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
33e00 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
33e10 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
33e20 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
33e30 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
33e40 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
33e50 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
33e60 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
33e70 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
33e80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
33e90 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
33ea0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33eb0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
33ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33ed0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
33ee0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
33ef0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33f00 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
33f10 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
33f20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
33f30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
33f40 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
33f50 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
33f60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33f70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33f80 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
33f90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33fa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33fb0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
33fc0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
33fd0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
33fe0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
33ff0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34000 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34010 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34020 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
34030 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
34040 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49  )(void*).);.SQLI
34050 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34060 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34070 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
34080 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
34090 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
340a0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
340b0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
340c0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
340d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
340e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
340f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34100 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
34110 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
34120 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
34130 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
34140 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
34150 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
34160 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
34170 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
34180 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
34190 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
341a0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
341b0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
341c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
341d0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
341e0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
341f0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
34200 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
34210 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34220 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
34230 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
34240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34250 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
34260 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
34270 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
34280 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
34290 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
342a0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
342b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
342c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
342d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
342e0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
342f0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
34300 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
34310 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
34320 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
34330 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
34340 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
34350 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
34360 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
34370 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
34380 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
34390 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
343a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
343b0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
343c0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
343d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
343e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
343f0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
34400 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
34410 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
34420 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
34430 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
34440 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
34450 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
34460 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
34470 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
34480 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
34490 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
344a0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
344b0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
344c0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
344d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
344e0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
344f0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
34500 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
34510 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
34520 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
34530 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
34540 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
34550 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
34560 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
34570 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
34580 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
34590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
345a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
345b0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
345c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
345d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
345e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
345f0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  n_v2()]..*/.SQLI
34600 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34610 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34620 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
34630 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
34640 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34650 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
34660 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
34670 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34690 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
346a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
346b0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
346c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
346d0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
346e0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
346f0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
34700 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
34710 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
34720 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
34730 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
34740 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
34750 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
34760 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
34770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
34780 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
34790 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
347a0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
347b0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
347c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
347d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
347e0 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
347f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
34800 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
34810 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
34820 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
34830 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
34840 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
34850 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
34860 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
34870 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
34880 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
34890 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
348a0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
348b0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
348c0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
348d0 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
348e0 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
348f0 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
34900 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
34910 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
34920 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
34930 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
34940 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
34950 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
34960 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34970 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
34980 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
349a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
349b0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
349c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
349d0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
349e0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
349f0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
34a00 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
34a10 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
34a20 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
34a30 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
34a40 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
34a50 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
34a60 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
34a70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
34a80 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
34a90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
34aa0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
34ab0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
34ac0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
34ad0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
34ae0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
34af0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
34b00 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
34b10 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
34b20 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
34b30 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
34b40 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
34b50 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
34b60 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
34b70 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
34b80 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
34b90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
34ba0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
34bb0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
34bc0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
34bd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34be0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
34bf0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
34c00 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
34c10 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
34c20 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
34c30 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
34c40 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
34c50 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
34c60 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
34c70 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
34c80 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
34c90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
34ca0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
34cb0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
34cc0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
34cd0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
34ce0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
34cf0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
34d00 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
34d10 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
34d20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
34d30 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
34d40 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
34d50 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
34d60 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
34d70 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
34d80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
34d90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34da0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
34db0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
34dc0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
34dd0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
34de0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
34df0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
34e00 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
34e10 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
34e20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
34e30 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
34e40 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
34e50 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
34e60 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
34e70 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
34e80 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
34e90 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
34ea0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
34eb0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
34ec0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
34ed0 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49  agraphs..*/.SQLI
34ee0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34ef0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
34f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34f10 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
34f20 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
34f30 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
34f40 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
34f50 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
34f60 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
34f70 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
34f80 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
34f90 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
34fa0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
34fb0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
34fc0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
34fd0 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
34fe0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
34ff0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
35000 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
35010 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
35020 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
35030 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
35040 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
35050 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35060 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
35070 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
35080 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
35090 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
350a0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
350b0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
350c0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
350d0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
350e0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
350f0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
35100 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35110 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
35120 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
35130 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
35140 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
35150 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
35160 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
35170 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
35180 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
35190 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
351a0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
351b0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
351c0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
351d0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
351e0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
351f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
35200 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
35210 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
35220 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
35230 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
35240 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
35250 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
35260 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
35270 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
35280 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
35290 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
352a0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
352b0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
352c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
352d0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
352e0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
352f0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
35300 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
35310 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
35320 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
35330 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
35340 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
35350 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
35360 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
35370 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
35380 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
35390 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
353a0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
353b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
353c0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
353d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
353e0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
353f0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
35400 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
35410 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
35420 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
35430 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
35440 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
35450 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
35460 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
35470 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
35480 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
35490 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
354a0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
354b0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
354c0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
354d0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
354e0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
354f0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35500 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
35510 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
35520 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35530 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
35540 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
35550 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
35560 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
35570 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
35580 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
35590 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
355a0 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
355b0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
355c0 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
355d0 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
355e0 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
355f0 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
35600 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
35610 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
35620 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
35630 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
35640 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
35650 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35660 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
35670 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35680 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
35690 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
356a0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
356b0 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
356c0 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
356d0 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
356e0 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
356f0 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
35700 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
35710 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
35720 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
35730 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
35740 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
35750 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
35760 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
35770 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
35780 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
35790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
357a0 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
357b0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
357c0 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
357d0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
357e0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
357f0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35800 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35810 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35820 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35830 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35840 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35850 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
35860 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35870 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
35880 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
35890 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
358a0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
358b0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
358c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
358d0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
358e0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
358f0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35900 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35910 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35920 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35930 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35940 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35950 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35960 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35970 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35980 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
35990 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
359a0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
359b0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
359c0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
359d0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
359e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
359f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35a00 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35a10 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35a20 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35a30 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35a40 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35a50 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35a60 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35a70 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35a80 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35a90 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35aa0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35ab0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
35ac0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
35ad0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
35ae0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
35af0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
35b00 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
35b10 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
35b20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
35b30 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
35b40 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
35b50 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
35b60 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35b70 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
35b80 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
35b90 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35ba0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35bb0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
35bc0 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
35bd0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
35be0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
35bf0 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a  data_directory;.
35c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35c10 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
35c20 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
35c30 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
35c40 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
35c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
35c60 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
35c70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35c80 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
35c90 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
35ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35cb0 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
35cc0 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
35cd0 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
35ce0 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
35cf0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
35d00 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
35d10 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
35d20 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
35d30 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
35d40 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
35d50 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
35d60 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
35d70 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
35d80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
35d90 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
35da0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
35db0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
35dc0 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
35dd0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
35de0 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
35df0 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
35e00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
35e10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
35e20 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
35e30 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
35e40 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
35e50 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
35e60 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
35e70 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
35e80 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
35e90 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
35ea0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
35eb0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
35ec0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
35ed0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
35ee0 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
35ef0 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
35f00 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
35f10 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
35f20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
35f30 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
35f40 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
35f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
35f60 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
35f70 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
35f80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35f90 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
35fa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
35fc0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
35fd0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
35fe0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
35ff0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
36000 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
36010 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
36020 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
36030 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
36040 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
36050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36060 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
36070 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
36080 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
36090 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
360a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
360b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
360c0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
360d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
360e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
360f0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
36100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36110 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
36120 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
36130 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
36140 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
36150 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
36160 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
36170 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
36180 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  place..*/.SQLITE
36190 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
361a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
361b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
361c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
361d0 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65   Return The File
361e0 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62  name For A Datab
361f0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
36200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36210 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c  3_db_filename(D,
36220 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
36230 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36240 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  o a filename.** 
36250 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
36260 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f  database N of co
36270 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68  nnection D.  ^Th
36280 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
36290 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20  file.** has the 
362a0 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66  name "main".  If
362b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74   there is no att
362c0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e  ached database N
362d0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
362e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
362f0 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65  , or if database
36300 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72   N is a temporar
36310 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y or in-memory d
36320 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a  atabase, then.**
36330 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
36340 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
36350 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  ** ^The filename
36360 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
36370 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  s function is th
36380 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a  e output of the.
36390 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  ** xFullPathname
363a0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
363b0 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72  VFS].  ^In other
363c0 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65   words, the file
363d0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  name.** will be 
363e0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
363f0 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68  name, even if th
36400 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a  e filename used.
36410 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ** to open the d
36420 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c  atabase original
36430 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20  ly was a URI or 
36440 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
36450 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
36460 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
36470 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
36480 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
36490 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
364a0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
364b0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69  REF: Determine i
364c0 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  f a database is 
364d0 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20  read-only.**.** 
364e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
364f0 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e  readonly(D,N) in
36500 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36510 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  1 if the databas
36520 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63  e N.** of connec
36530 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f  tion D is read-o
36540 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20  nly, 0 if it is 
36550 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d  read/write, or -
36560 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a  1 if N is not.**
36570 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64   the name of a d
36580 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65  atabase on conne
36590 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49  ction D..*/.SQLI
365a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
365b0 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73  e3_db_readonly(s
365c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
365d0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
365e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
365f0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
36600 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36610 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
36620 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36630 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36640 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
36650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
36660 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
36670 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36690 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
366a0 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
366b0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
366c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
366d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
366e0 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
366f0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
36700 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
36710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36720 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
36730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36740 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
36750 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
36760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
36770 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
36780 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
36790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
367a0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
367b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
367c0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
367d0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
367e0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
367f0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
36800 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
36810 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
36820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
36830 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
36840 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
36850 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
36860 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
36870 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
36880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36890 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
368a0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
368b0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
368c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
368d0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
368e0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
368f0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
36900 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
36910 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
36920 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
36930 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
36940 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
36950 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
36960 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
36970 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
36980 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
36990 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
369a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
369b0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
369c0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
369d0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
369e0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
369f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
36a00 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
36a10 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
36a20 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
36a30 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
36a40 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
36a50 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
36a60 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
36a70 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
36a80 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
36a90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
36aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36ab0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
36ac0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
36ad0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
36ae0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
36af0 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
36b00 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
36b10 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
36b20 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
36b30 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
36b40 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
36b50 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
36b60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
36b70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
36b80 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
36b90 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
36ba0 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
36bb0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
36bc0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
36bd0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
36be0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
36bf0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
36c00 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
36c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c20 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
36c30 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
36c40 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
36c50 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
36c60 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20   The commit and 
36c70 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
36c80 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20  llbacks are not 
36c90 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68  reentrant..** Th
36ca0 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
36cb0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
36cc0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
36cd0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
36ce0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
36cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
36d00 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
36d10 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
36d20 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
36d30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
36d40 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
36d50 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
36d60 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
36d70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
36d80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
36d90 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
36da0 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
36db0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
36dc0 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
36dd0 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
36de0 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f  at running any o
36df0 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65  ther SQL stateme
36e00 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53  nts, including S
36e10 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
36e20 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63  ,.** or merely c
36e30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
36e40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
36e50 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
36e60 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  )] will modify.*
36e70 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
36e80 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
36e90 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
36ea0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
36eb0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
36ec0 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
36ed0 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
36ee0 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
36ef0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
36f00 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
36f10 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
36f20 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
36f30 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
36f40 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
36f50 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
36f60 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
36f70 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
36f80 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
36f90 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
36fa0 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
36fb0 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
36fc0 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
36fd0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
36fe0 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
36ff0 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
37000 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
37010 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
37020 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
37030 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
37040 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
37050 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
37060 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
37070 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
37080 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
37090 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
370a0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
370b0 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
370c0 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
370d0 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
370e0 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
370f0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
37100 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
37110 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
37120 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
37130 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
37140 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
37150 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37160 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
37170 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
37180 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
37190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
371a0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
371b0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
371c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
371d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
371e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
371f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
37200 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
37210 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
37220 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
37230 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
37240 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
37250 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
37260 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
37270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37280 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
37290 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
372a0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
372b0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
372c0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
372d0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
372e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
372f0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
37300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37310 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
37320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37330 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
37340 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
37350 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
37360 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
37370 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
37380 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
37390 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
373a0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
373b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
373c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
373d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
373e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
373f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
37400 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
37410 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
37420 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
37430 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
37440 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
37450 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
37460 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
37470 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
37480 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
37490 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
374a0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
374b0 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
374c0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
374d0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
374e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
374f0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
37500 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
37510 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
37520 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
37530 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
37540 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
37550 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
37560 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
37570 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
37580 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37590 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
375a0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
375b0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
375c0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
375d0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
375e0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
375f0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
37600 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
37610 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
37620 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
37630 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
37640 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
37650 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
37660 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
37670 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
37680 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
37690 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
376a0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
376b0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
376c0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
376d0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
376e0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
376f0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
37700 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
37710 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
37720 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
37730 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
37740 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
37750 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
37760 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
37770 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
37780 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
37790 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
377a0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
377b0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
377c0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
377d0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
377e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
377f0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
37800 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
37810 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
37820 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
37830 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
37840 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
37850 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
37860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37870 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
37880 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
37890 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
378a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
378b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
378c0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
378d0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
378e0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
378f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37900 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
37910 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
37920 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
37930 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37940 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
37950 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
37960 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
37970 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
37980 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
37990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
379a0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
379b0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
379c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
379d0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
379e0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
379f0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
37a00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37a10 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37a20 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
37a30 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
37a40 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
37a50 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
37a60 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
37a70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37a80 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
37a90 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
37aa0 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
37ab0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
37ac0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37ad0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
37ae0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37af0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
37b00 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
37b10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
37b20 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
37b30 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
37b40 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
37b50 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
37b60 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
37b70 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
37b80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
37b90 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
37ba0 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
37bb0 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20  ger Cache.**.** 
37bc0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
37bd0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
37be0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
37bf0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
37c00 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
37c10 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
37c20 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
37c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37c40 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
37c50 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
37c60 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
37c70 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
37c80 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
37c90 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
37ca0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
37cb0 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
37cc0 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
37cd0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
37ce0 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
37cf0 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
37d00 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
37d10 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
37d20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
37d30 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
37d40 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
37d50 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
37d60 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
37d70 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
37d80 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
37d90 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
37da0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
37db0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
37dc0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
37dd0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
37de0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37df0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
37e00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
37e10 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
37e20 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
37e30 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
37e40 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
37e50 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
37e60 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
37e70 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
37e80 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
37e90 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
37ea0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
37eb0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
37ec0 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
37ed0 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
37ee0 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
37ef0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
37f00 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
37f10 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
37f20 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
37f30 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
37f40 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
37f50 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
37f60 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
37f70 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
37f80 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
37f90 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
37fa0 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
37fb0 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
37fc0 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
37fd0 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
37fe0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
37ff0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
38000 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Mode].*/.SQLITE_
38010 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38020 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38030 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
38040 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
38050 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
38060 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
38070 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
38080 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
38090 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
380a0 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
380b0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
380c0 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
380d0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
380e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
380f0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
38100 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
38110 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
38120 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38130 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
38140 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
38150 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
38160 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
38170 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
38180 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
38190 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
381a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
381b0 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
381c0 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
381d0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
381e0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
381f0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
38200 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
38210 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
38220 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
38230 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
38240 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
38250 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
38260 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
38270 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
38280 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  T]..**.** See al
38290 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  so: [sqlite3_db_
382a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
382b0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
382c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
382d0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
382e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
382f0 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73  : Free Memory Us
38300 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65  ed By A Database
38310 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
38320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
38330 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
38340 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  (D) interface at
38350 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61  tempts to free a
38360 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d  s much heap.** m
38370 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c  emory as possibl
38380 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  e from database 
38390 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e  connection D. Un
383a0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  like the.** [sql
383b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
383c0 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ory()] interface
383d0 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  , this interface
383e0 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a   is effect even.
383f0 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51  ** when then [SQ
38400 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
38410 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63  RY_MANAGEMENT] c
38420 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
38430 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64  on is.** omitted
38440 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
38450 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  : [sqlite3_relea
38460 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
38470 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
38480 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73  qlite3_db_releas
38490 65 5f 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65 33  e_memory(sqlite3
384a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
384b0 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
384c0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
384d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
384e0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
384f0 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  mit64() interfac
38500 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75  e sets and/or qu
38510 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66  eries the.** sof
38520 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  t limit on the a
38530 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
38540 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
38550 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
38560 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  Lite..** ^SQLite
38570 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70   strives to keep
38580 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69   heap memory uti
38590 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74  lization below t
385a0 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20  he soft heap.** 
385b0 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e  limit by reducin
385c0 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  g the number of 
385d0 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68  pages held in th
385e0 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20  e page cache.** 
385f0 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75  as heap memory u
38600 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73  sages approaches
38610 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
38620 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
38630 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65  mit is "soft" be
38640 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67  cause even thoug
38650 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73  h SQLite strives
38660 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f   to stay.** belo
38670 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20  w the limit, it 
38680 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20  will exceed the 
38690 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61  limit rather tha
386a0 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e  n generate.** an
386b0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
386c0 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72  error.  In other
386d0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74   words, the soft
386e0 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20   heap limit .** 
386f0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
38700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
38710 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
38720 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
38730 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68  _limit64() is th
38740 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
38750 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
38760 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
38770 6c 6c 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20