System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f950c88e5f2b4930b34efb4c446daab238cb49c8:


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 39 2d 30 33 20 31 35 3a 34 32 3a 33 36 20  -09-03 15:42:36 
1080: 63 30 64 38 39 64 34 61 39 37 35 32 39 32 32 66  c0d89d4a9752922f
1090: 39 65 33 36 37 33 36 32 33 36 36 65 66 64 65 34  9e367362366efde4
10a0: 66 31 62 30 36 66 32 61 22 0a 0a 2f 2a 0a 2a 2a  f1b06f2a"../*.**
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 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
5ef0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5f00: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5f10: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5f20: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5f30: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5f40: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5f50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5f60: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5f70: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f90: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5fa0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5fb0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5fc0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5fe0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5ff0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6000: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6010: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6020: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6030: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6040: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6050: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6060: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6070: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6080: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6090: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
60a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
60b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
60c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
60d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
60e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
60f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6100: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6110: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6120: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6130: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6140: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6150: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6160: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6170: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6180: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6190: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
61a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
61b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
61c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
61d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
61e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
61f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6200: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6210: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6220: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6230: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6240: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6250: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6260: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6270: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6280: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6290: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
62a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
62b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
62c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
62d0: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
62e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
62f0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6300: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6330: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6340: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6350: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6360: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6370: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6390: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
63a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63b0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
63c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63d0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
63e0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
63f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6400: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6410: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6420: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6430: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6440: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6450: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6470: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6480: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6490: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
64b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
64c0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
64d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
64e0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
64f0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6510: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6520: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6530: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6550: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6560: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6580: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6590: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
65a0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
65b0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
65c0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
65d0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
65e0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
65f0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6600: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6610: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6620: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6630: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6640: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6650: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6660: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6690: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
66a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66b0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
66c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
66d0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
66e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
66f0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6700: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6710: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6720: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6730: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6740: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6750: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6760: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6770: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6780: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6790: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
67a0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
67b0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
67c0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
67d0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
67e0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
67f0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6800: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6810: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6820: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6830: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6840: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6850: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6860: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6870: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6880: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
6890: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
68a0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
68b0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
68c0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
68d0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
68e0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
68f0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
6900: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
6910: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
6920: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6930: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
6940: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
6950: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6960: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
6970: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
6980: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
6990: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
69a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
69b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
69c0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
69d0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
69e0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
69f0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
6a00: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
6a10: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
6a20: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
6a30: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
6a40: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
6a50: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
6a60: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
6a70: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
6a80: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
6a90: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
6aa0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ab0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ac0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
6ad0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
6ae0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
6af0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
6b00: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
6b10: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
6b20: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
6b30: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
6b40: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
6b50: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
6b60: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
6b70: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
6b80: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
6b90: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
6ba0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
6bb0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6bc0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
6bd0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
6be0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
6bf0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
6c00: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
6c10: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
6c20: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
6c30: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6c50: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6c60: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6c70: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6c80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ca0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6cb0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6cd0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
6ce0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
6cf0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6d00: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
6d10: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
6d20: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
6d30: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6d40: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6d50: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6d60: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6d70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6d80: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6d90: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6da0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6db0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6dc0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6dd0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6de0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6df0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6e00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6e10: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6e20: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6e30: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6e40: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6e50: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6e60: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6e70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6e80: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6e90: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6ea0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6eb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6ec0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6ed0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6ee0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6ef0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6f00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6f10: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6f20: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6f30: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6f40: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6f50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6f60: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
6f70: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6f80: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6f90: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6fa0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6fb0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6fc0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6fd0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
6fe0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
6ff0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7000: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7010: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7020: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7030: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7040: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7050: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7060: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7070: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7080: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7090: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
70a0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
70b0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
70c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
70d0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
70e0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
70f0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7100: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7110: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7120: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7130: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7140: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7150: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7160: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7170: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7180: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7190: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
71a0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
71b0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
71c0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
71d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
71e0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
71f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7200: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7210: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7220: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7230: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7240: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7250: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7270: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7280: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7290: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
72a0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
72b0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
72c0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
72d0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
72e0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
72f0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7300: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7310: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7320: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7330: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7340: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7350: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7360: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7370: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7380: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7390: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
73a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
73b0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
73d0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
73e0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
73f0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7410: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7420: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7430: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7440: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7450: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7460: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7470: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7480: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7490: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
74a0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
74b0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
74c0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
74d0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
74e0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
74f0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7500: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7510: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7520: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7530: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7540: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7550: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7560: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7570: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7580: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7590: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
75a0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
75b0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
75c0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
75d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
75e0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
75f0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7600: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7610: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7620: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7630: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7640: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7650: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7660: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7670: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7680: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7690: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
76a0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
76b0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
76c0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
76d0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
76e0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
76f0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7700: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7710: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7720: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7730: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7740: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7750: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7760: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7770: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7780: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7790: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
77a0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
77b0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
77c0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
77d0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
77e0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
77f0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7800: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7810: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7820: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7830: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
7840: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
7850: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7860: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7870: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7880: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7890: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
78a0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
78b0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
78c0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
78d0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
78e0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
78f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7900: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7910: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7920: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7930: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7940: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7950: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
7960: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
7970: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
7980: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
7990: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
79a0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
79b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79c0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
79d0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
79e0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
79f0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7a00: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7a10: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7a20: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7a30: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7a40: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7a50: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
7a60: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
7a70: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
7a80: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
7a90: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
7aa0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
7ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ad0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
7ae0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
7b00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
7b20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7b40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7b60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7b80: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
7ba0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7bc0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
7bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7be0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
7bf0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
7c00: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
7c10: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
7c20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7c30: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7c40: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
7c50: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
7c60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7c80: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
7c90: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
7ca0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
7cb0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
7cc0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
7cd0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
7ce0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
7cf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
7d00: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
7d10: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7d20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7d30: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
7d40: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
7d50: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
7d60: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
7d70: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
7d80: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
7d90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7da0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7db0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7dc0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7dd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7de0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7df0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7e00: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7e10: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7e20: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7e30: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
7e40: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
7e50: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
7e60: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
7e70: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
7e80: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
7e90: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
7ea0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
7eb0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
7ec0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
7ed0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
7ee0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
7ef0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
7f00: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
7f10: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
7f20: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7f30: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
7f40: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
7f50: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
7f60: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
7f70: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7f80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
7f90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
7fa0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7fb0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
7fc0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
7fd0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
7fe0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7ff0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8000: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8010: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8020: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8030: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8040: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8050: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8060: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8070: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8080: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
80a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
80b0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
80c0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
80d0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
80e0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
80f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8100: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8110: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8120: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8130: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8140: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8150: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8160: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8170: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8180: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8190: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
81a0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
81b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
81c0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
81d0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
81e0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
81f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8200: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8210: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8220: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8230: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8240: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8250: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8260: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8270: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8280: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8290: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
82a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
82b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
82c0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
82d0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
82e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
82f0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8300: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8310: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8320: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8330: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8340: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8350: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8360: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
8370: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8380: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8390: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
83a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
83b0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
83c0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
83d0: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
83e0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
83f0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8400: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8410: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8420: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8430: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8440: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8450: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8460: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8470: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
8480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8490: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
84a0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
84b0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
84c0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
84d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
84e0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
84f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8500: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8510: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8520: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8530: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8540: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8550: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8560: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8570: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8580: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8590: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
85a0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
85b0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
85c0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
85d0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
85e0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
85f0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8600: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8610: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8620: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8630: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8650: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8670: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8680: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8690: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
86a0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
86b0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
86c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
86d0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
86e0: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
86f0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8700: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8710: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8720: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8730: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8740: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8750: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8760: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8770: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8780: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8790: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
87a0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
87b0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
87c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
87d0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
87e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
87f0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8800: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8810: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8820: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8830: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8840: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8850: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8860: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8870: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8880: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8890: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
88a0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
88b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
88c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
88d0: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
88e0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
88f0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8900: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8910: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8920: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8930: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8940: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8950: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8960: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8970: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8980: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8990: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
89a0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
89b0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
89c0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
89d0: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
89e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
89f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8a00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8a10: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8a20: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8a30: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8a40: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8a50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a60: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
8a70: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
8a80: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
8a90: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
8aa0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
8ab0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8ac0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
8ad0: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
8ae0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
8af0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8b00: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8b10: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
8b20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8b30: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8b40: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8b50: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8b60: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8b70: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8b80: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8b90: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8ba0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8bb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8bc0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8bd0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8be0: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8bf0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8c00: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8c10: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8c20: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8c30: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8c40: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8c50: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8c60: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8c70: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8c80: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8c90: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8ca0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8cb0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8cc0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8cd0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8ce0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8cf0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8d00: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8d10: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8d20: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8d30: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8d40: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8d50: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8d60: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
8d70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8d80: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
8da0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8db0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
8dc0: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
8dd0: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
8de0: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
8df0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
8e00: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
8e10: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
8e20: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
8e30: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
8e40: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8e50: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
8e60: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
8e70: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
8e80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
8e90: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
8ea0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
8eb0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
8ec0: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
8ed0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
8ee0: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
8ef0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
8f00: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8f10: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
8f20: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
8f30: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
8f40: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
8f50: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
8f60: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
8f70: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
8f80: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
8f90: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
8fa0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
8fb0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
8fc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
8fd0: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
8fe0: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
8ff0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
9000: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
9010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
9020: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
9030: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
9040: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9050: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9060: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9070: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9080: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
9090: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
90a0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
90b0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
90c0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
90d0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
90e0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
90f0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9100: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9110: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9120: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9130: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9140: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9150: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9160: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9170: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9180: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9190: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
91a0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
91b0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
91c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
91d0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
91e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
91f0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9200: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9210: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9220: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9230: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
9240: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9250: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
9260: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
9270: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
9280: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
9290: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
92a0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
92b0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
92c0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
92d0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
92e0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
92f0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
9300: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
9310: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
9320: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
9330: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
9340: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9350: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
9360: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
9370: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
9380: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
9390: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
93a0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
93b0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
93c0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
93d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
93e0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
93f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9400: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
9410: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9420: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
9430: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
9440: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9450: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
9460: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9470: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9480: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9490: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
94a0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
94b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
94c0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
94d0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
94e0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
94f0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9500: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9510: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9520: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9530: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9540: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9550: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9560: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
9570: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
9580: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9590: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
95a0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
95b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
95c0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
95d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
95e0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
95f0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9600: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9610: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9620: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9630: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9640: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9650: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
9660: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9670: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
9680: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
9690: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
96a0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
96b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
96c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
96d0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
96e0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
96f0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9700: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9710: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9720: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9730: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9740: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9750: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
9760: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9770: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9780: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9790: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
97a0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
97b0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
97c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
97d0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
97e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
97f0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9800: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9810: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9820: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9830: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9840: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9850: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
9860: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
9870: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
9880: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
9890: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
98a0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
98b0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
98c0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
98d0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
98e0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
98f0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9900: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9910: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9920: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9930: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9940: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9950: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
9960: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
9970: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
9980: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
9990: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
99a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
99b0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
99c0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
99d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
99e0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
99f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9a00: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9a10: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9a20: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9a30: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9a40: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
9a50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9a60: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
9a70: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
9a80: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
9a90: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
9aa0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
9ab0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
9ac0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
9ad0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
9ae0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
9af0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
9b00: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
9b10: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
9b20: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
9b30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9b40: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
9b50: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
9b60: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9b70: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
9b80: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
9b90: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
9ba0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
9bb0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
9bc0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9be0: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
9bf0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
9c00: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
9c10: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
9c20: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
9c30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
9c40: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
9c50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9c60: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
9c70: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
9c80: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
9c90: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
9ca0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
9cb0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
9cc0: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
9cd0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9ce0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
9cf0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
9d00: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
9d10: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
9d20: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
9d30: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
9d40: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
9d50: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
9d60: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
9d70: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
9d80: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
9d90: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
9da0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
9db0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
9dc0: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
9dd0: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
9de0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
9df0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
9e00: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
9e10: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
9e20: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
9e30: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
9e40: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
9e50: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
9e60: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
9e70: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
9e80: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
9e90: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
9ea0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
9eb0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
9ec0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
9ed0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
9ee0: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9f00: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
9f10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
9f20: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
9f30: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
9f40: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
9f50: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
9f60: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
9f70: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
9f80: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
9f90: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
9fa0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
9fb0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
9fc0: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
9fd0: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
9fe0: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
9ff0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
a000: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
a010: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
a020: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a030: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a040: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a050: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
a060: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
a070: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
a080: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a090: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
a0a0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
a0b0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a0c0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a0d0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a0e0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a0f0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a100: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a110: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a130: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a140: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a150: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a160: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a170: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a180: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a190: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a1a0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a1b0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
a1c0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
a1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
a1e0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
a1f0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
a200: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
a210: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
a220: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
a230: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
a240: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a250: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
a260: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
a270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
a280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a290: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
a2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a2c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
a2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
a2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a2f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
a300: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
a310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a320: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
a330: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a350: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a360: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
a370: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a380: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
a390: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
a3a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a3b0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
a3c0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
a3d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
a3e0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
a3f0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
a400: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
a410: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a420: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a440: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
a450: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
a460: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
a470: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
a480: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
a490: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
a4a0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
a4b0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
a4c0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
a4d0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
a4e0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
a4f0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
a500: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
a510: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
a520: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
a530: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
a540: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
a550: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
a560: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
a570: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
a580: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
a590: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
a5a0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
a5b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a5c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
a5d0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
a5e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
a5f0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
a600: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
a610: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
a620: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
a630: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
a640: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
a650: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
a660: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
a670: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
a680: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
a690: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
a6a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
a6b0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
a6c0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
a6d0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
a6e0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
a6f0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
a700: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
a710: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
a720: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
a730: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
a740: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
a750: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
a760: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
a770: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
a780: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
a790: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
a7a0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
a7b0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
a7c0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
a7d0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
a7e0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
a7f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
a800: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
a810: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a820: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
a830: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
a840: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
a850: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
a860: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
a870: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
a880: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
a890: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
a8a0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
a8b0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
a8c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
a8d0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
a8e0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
a8f0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
a900: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
a910: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
a920: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
a930: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
a940: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
a950: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
a960: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
a970: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
a980: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
a990: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
a9a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
a9b0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
a9c0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
a9d0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
a9e0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
a9f0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
aa00: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
aa10: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
aa20: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
aa30: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
aa40: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
aa50: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
aa60: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
aa70: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
aa80: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
aa90: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
aaa0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
aab0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
aac0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
aad0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
aae0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
aaf0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
ab00: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
ab10: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
ab20: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
ab30: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
ab40: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
ab50: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ab60: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
ab70: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
ab80: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
ab90: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
aba0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
abb0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
abc0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
abd0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
abe0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
abf0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
ac00: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
ac10: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
ac20: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
ac30: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
ac40: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
ac50: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ac60: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ac70: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ac80: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
ac90: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
aca0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
acb0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
acc0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
acd0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
ace0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
acf0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
ad00: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
ad10: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ad20: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ad30: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ad40: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
ad50: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
ad60: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
ad70: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
ad80: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
ad90: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
ada0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
adb0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
adc0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
add0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
ade0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
adf0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
ae00: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
ae10: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
ae20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
ae30: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
ae40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ae50: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
ae60: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
ae70: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
ae80: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
ae90: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
aea0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
aeb0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
aec0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
aed0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
aee0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
aef0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
af00: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
af10: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
af20: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
af30: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
af40: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
af50: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
af60: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
af70: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
af80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
af90: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
afa0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
afb0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
afc0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
afd0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
afe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
aff0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b000: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
b010: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
b020: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
b030: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
b040: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
b050: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
b060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
b070: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
b080: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
b090: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
b0a0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
b0b0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b0c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b0d0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b0e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b0f0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b100: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b110: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b120: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b130: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b140: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b150: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b160: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b170: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b180: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b1b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b1c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b1d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b1e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b1f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
b200: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b210: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
b220: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b230: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
b240: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b250: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
b260: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
b280: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
b290: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b2a0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
b2b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
b2c0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
b2d0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
b2e0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
b2f0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
b300: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
b310: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
b320: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
b330: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
b340: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
b350: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
b360: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
b370: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
b380: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
b390: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
b3a0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
b3b0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
b3c0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
b3d0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
b3e0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
b3f0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
b400: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
b410: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
b420: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
b430: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
b440: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
b450: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
b460: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
b470: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
b480: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
b490: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
b4a0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
b4b0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
b4c0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
b4d0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
b4e0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
b4f0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
b500: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
b510: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
b520: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
b530: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b540: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b550: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
b560: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
b570: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b580: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
b590: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
b5a0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
b5b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
b5c0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
b5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
b5e0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
b5f0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
b600: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
b610: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
b620: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
b630: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
b640: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
b650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
b660: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
b670: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
b680: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
b690: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
b6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
b6b0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
b6c0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
b6d0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
b6e0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
b6f0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
b700: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
b710: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
b720: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
b730: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
b740: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
b750: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
b760: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
b770: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b780: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
b790: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
b7a0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
b7b0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
b7c0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
b7d0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
b7e0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
b7f0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
b800: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
b810: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
b820: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
b830: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
b840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
b850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
b860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
b870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
b880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
b890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
b8a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
b8b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
b8c0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b8d0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
b8e0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
b8f0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
b900: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
b910: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
b920: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
b930: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
b940: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b950: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
b960: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
b970: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b980: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
b990: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
b9a0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
b9b0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
b9c0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
b9d0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
b9e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
b9f0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
ba00: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
ba10: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
ba20: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
ba30: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
ba40: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
ba50: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
ba60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
ba70: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
ba80: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ba90: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
baa0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
bab0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
bac0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
bad0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
bae0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
baf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
bb00: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
bb10: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
bb20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
bb30: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
bb40: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
bb50: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
bb60: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
bb70: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
bb80: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
bb90: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
bba0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
bbb0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
bbc0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
bbd0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
bbe0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
bbf0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
bc00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
bc10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
bc20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
bc30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
bc40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
bc50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
bc60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
bc70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
bc80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
bc90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
bca0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
bcb0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
bcc0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
bcd0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
bce0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
bcf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
bd00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
bd10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
bd20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
bd30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
bd40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
bd50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
bd60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
bd70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
bd80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
bd90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
bda0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
bdb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
bdc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
bdd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
bde0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
bdf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
be00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
be10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
be20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
be30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
be40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
be50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
be60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
be70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
be80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
be90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
bea0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
beb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
bec0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
bed0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
bee0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
bef0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
bf00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
bf10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
bf20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
bf30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
bf40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
bf50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
bf60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
bf70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
bf80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
bf90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
bfa0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
bfb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bfc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
bfd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
bfe0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
bff0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
c000: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
c010: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
c020: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
c030: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
c040: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
c050: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
c060: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c070: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
c080: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
c090: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
c0a0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
c0b0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c0c0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c0d0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c0e0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c0f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c100: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c110: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c120: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c130: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c140: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c150: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c160: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c170: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c180: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c190: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c1a0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c1b0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c1c0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c1d0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c1e0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c1f0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
c200: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
c210: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
c220: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
c230: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
c240: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
c250: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
c260: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
c270: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
c280: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
c290: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
c2a0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
c2b0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
c2c0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
c2d0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
c2e0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
c2f0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
c300: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
c310: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
c320: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
c330: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
c340: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
c350: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
c360: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
c370: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
c380: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
c390: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
c3a0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
c3b0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
c3c0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
c3d0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
c3e0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
c3f0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
c400: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
c410: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
c420: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
c430: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
c440: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
c450: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
c460: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
c470: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
c480: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c490: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
c4a0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
c4b0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
c4c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
c4d0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
c4e0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
c4f0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
c500: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
c510: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
c520: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
c530: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
c540: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
c550: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
c560: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
c570: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
c580: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
c590: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
c5a0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
c5b0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
c5c0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
c5d0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
c5e0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
c5f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
c600: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
c610: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
c620: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
c630: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
c640: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
c650: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
c660: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
c670: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
c680: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c690: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c6a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
c6b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
c6c0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
c6d0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
c6e0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
c6f0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c700: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c710: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
c720: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
c730: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c740: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c750: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
c760: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
c770: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
c780: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c790: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c7a0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
c7b0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
c7c0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
c7d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
c7e0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
c7f0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
c800: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c810: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c820: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
c830: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
c840: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
c850: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
c860: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
c870: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
c880: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
c890: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
c8a0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
c8b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
c8c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
c8d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
c8e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c8f0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
c900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
c910: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
c920: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
c930: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
c940: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
c950: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
c960: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
c970: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
c980: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
c990: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c9a0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
c9b0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
c9c0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
c9d0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
c9e0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
c9f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ca00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ca10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ca20: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ca30: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ca40: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ca50: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
ca60: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
ca70: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
ca80: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
ca90: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
caa0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
cab0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
cac0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
cad0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cae0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
caf0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
cb00: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
cb10: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
cb20: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
cb30: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
cb40: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
cb50: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
cb60: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cb70: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cb80: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
cb90: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
cba0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
cbb0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
cbc0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
cbd0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
cbe0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
cbf0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
cc00: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
cc10: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
cc20: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
cc30: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
cc40: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
cc50: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
cc60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
cc70: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
cc80: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cc90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cca0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
ccb0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
ccc0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
ccd0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
cce0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
ccf0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
cd00: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
cd10: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
cd20: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
cd30: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
cd40: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
cd50: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cd60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
cd70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
cd80: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
cd90: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
cda0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
cdb0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
cdc0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
cdd0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cde0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cdf0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
ce00: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
ce10: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
ce20: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
ce30: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
ce40: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
ce50: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
ce60: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
ce70: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
ce80: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ce90: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
cea0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ceb0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
cec0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ced0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
cee0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
cef0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
cf00: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
cf10: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
cf20: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cf30: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
cf40: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cf50: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cf60: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
cf70: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
cf80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
cf90: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
cfa0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
cfb0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
cfc0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
cfd0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
cfe0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
cff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d000: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
d010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d020: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
d030: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
d040: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
d050: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
d060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d070: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
d080: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
d090: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d0a0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
d0b0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d0c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d0d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d0e0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d0f0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d100: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d110: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d120: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d140: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d150: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d160: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d170: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d180: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d190: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d1b0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d1c0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d1d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d1e0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d1f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
d200: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d210: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
d220: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
d230: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
d240: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
d250: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
d260: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
d270: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
d280: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
d290: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
d2a0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
d2b0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
d2c0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
d2d0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
d2e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
d2f0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
d300: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
d310: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
d320: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
d330: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
d340: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
d350: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
d360: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
d370: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
d380: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d390: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
d3a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d3b0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
d3c0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d3d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d3e0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
d3f0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
d400: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
d410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
d420: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
d430: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
d440: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
d450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d460: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
d470: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
d480: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
d490: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
d4a0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
d4b0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
d4c0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
d4d0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
d4e0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
d4f0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
d500: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
d510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
d520: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
d530: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
d540: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
d550: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
d560: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
d570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d580: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
d590: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
d5a0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
d5b0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d5c0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
d5d0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
d5e0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
d5f0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
d600: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d610: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
d620: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
d630: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
d640: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
d650: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
d660: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
d670: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
d680: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
d690: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
d6a0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
d6b0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
d6c0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
d6d0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
d6e0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d6f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d700: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
d710: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d720: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
d730: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
d740: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
d750: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
d760: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
d770: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
d780: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d790: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d7a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d7b0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
d7c0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
d7d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d7e0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
d7f0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
d800: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
d810: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
d820: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
d830: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
d840: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
d850: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
d860: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
d870: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d880: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
d890: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
d8a0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
d8b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d8c0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
d8d0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
d8e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
d8f0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
d900: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
d910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d920: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
d930: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
d940: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
d950: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
d960: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
d970: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d990: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d9a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
d9b0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
d9c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d9d0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
d9e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d9f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
da00: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
da10: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
da20: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
da30: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
da40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
da50: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
da60: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
da70: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
da80: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
da90: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
daa0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
dab0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
dac0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
dad0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
dae0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
daf0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
db00: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
db10: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
db20: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
db30: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
db40: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
db50: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
db60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
db70: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
db80: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
db90: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
dba0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
dbb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
dbc0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
dbd0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
dbe0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
dbf0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
dc00: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
dc10: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
dc20: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
dc30: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
dc40: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
dc50: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
dc60: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
dc70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dc80: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
dc90: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
dca0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
dcb0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dcc0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
dcd0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
dce0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
dcf0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
dd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dd10: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
dd20: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
dd30: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
dd40: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
dd50: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
dd60: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dd70: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
dd80: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
dd90: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
dda0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
ddb0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
ddc0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
ddd0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
dde0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
ddf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de00: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
de10: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
de20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
de30: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
de40: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
de50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
de60: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
de70: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
de80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
de90: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
dea0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
deb0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
dec0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
ded0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
dee0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
def0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
df00: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
df10: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
df20: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
df30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
df40: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
df50: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
df60: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
df70: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
df80: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
df90: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
dfa0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
dfb0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
dfc0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
dfd0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
dfe0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
dff0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
e000: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
e010: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
e020: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
e030: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
e040: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e060: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
e070: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
e080: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
e090: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
e0a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
e0b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e0c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e0d0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e0e0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e0f0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e100: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e110: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e120: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e130: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e140: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e150: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e160: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e170: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e180: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e190: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e1a0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e1b0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e1c0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e1d0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e1e0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e1f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e200: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
e210: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e220: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
e230: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
e240: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
e250: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
e260: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
e270: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
e280: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
e290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e2a0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
e2b0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
e2c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e2d0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
e2e0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
e2f0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
e300: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e310: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
e320: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
e330: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
e340: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
e350: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
e360: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
e370: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
e380: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
e390: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
e3a0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
e3b0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
e3c0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
e3d0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
e3e0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
e3f0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
e400: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
e410: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
e420: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
e430: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
e440: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
e450: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
e460: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
e470: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e480: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
e490: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
e4a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
e4b0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
e4c0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
e4d0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
e4e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
e4f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
e500: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
e510: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
e520: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
e530: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
e540: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
e550: 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
e560: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
e580: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
e590: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
e5a0: 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
e5b0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e5c0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
e5d0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
e5e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
e5f0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
e600: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
e610: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
e620: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
e630: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e640: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
e650: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
e660: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
e670: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
e680: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
e690: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
e6a0: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
e6b0: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
e6c0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
e6d0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
e6e0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
e6f0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
e700: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
e710: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
e720: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
e730: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
e740: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
e750: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
e760: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
e770: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
e780: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e790: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e7a0: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
e7b0: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
e7c0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
e7d0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
e7e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
e7f0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
e800: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
e810: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
e820: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
e830: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
e840: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
e850: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
e860: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
e870: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
e880: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
e890: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
e8a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
e8b0: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
e8c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
e8d0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
e8e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e8f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
e900: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
e910: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
e920: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
e930: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
e940: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
e950: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
e960: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
e970: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
e980: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
e990: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
e9a0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
e9b0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
e9c0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
e9d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
e9e0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
e9f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
ea00: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
ea10: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
ea20: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
ea30: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
ea40: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
ea50: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
ea60: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
ea70: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
ea80: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
ea90: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
eaa0: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
eab0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
eac0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
ead0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
eae0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
eaf0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
eb00: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
eb10: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
eb20: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
eb30: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
eb40: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
eb50: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
eb60: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
eb70: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
eb80: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
eba0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
ebb0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
ebc0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
ebd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ebe0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
ebf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
ec00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ec10: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
ec20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
ec30: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
ec40: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
ec50: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
ec60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
ec70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
ec80: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
ec90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eca0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
ecb0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
ecc0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
ecd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ece0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
ecf0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ed00: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
ed10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ed20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
ed30: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
ed40: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
ed50: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ed60: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
ed70: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
ed80: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
ed90: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
eda0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
edb0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
edc0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
edd0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
ede0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
edf0: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
ee00: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
ee20: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
ee30: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ee40: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
ee50: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
ee60: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
ee70: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
ee80: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
ee90: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
eea0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
eeb0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
eec0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
eed0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
eee0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
eef0: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
ef00: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
ef10: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ef20: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ef30: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
ef40: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
ef50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
ef60: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
ef70: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
ef80: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
ef90: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
efa0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
efb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
efc0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
efd0: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
efe0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
eff0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f000: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f010: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f020: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f030: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f040: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f050: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f060: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f070: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f080: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f090: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f0a0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f0b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f0c0: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f0d0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f0e0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f0f0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f100: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f110: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f120: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f130: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f140: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f150: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f160: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f170: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f180: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f190: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f1a0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f1b0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f1c0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f1d0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f1e0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f1f0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f200: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f210: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f220: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f230: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f240: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f250: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f260: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f270: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f280: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f290: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f2a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f2b0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f2c0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f2d0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f2e0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f2f0: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f300: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f310: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f320: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f330: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f340: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f350: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f360: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f370: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f380: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f390: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f3a0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f3b0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f3c0: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f3d0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f3e0: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f3f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f400: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f410: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f420: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f430: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f440: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f450: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f460: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f470: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f480: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f490: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f4a0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f4b0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f4c0: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f4d0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f4e0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f4f0: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f500: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f510: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f520: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f530: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f540: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f550: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f560: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f570: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f580: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f590: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f5a0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f5b0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f5c0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f5d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f5e0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f5f0: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f600: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f610: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f620: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f630: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f640: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f650: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f660: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f670: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f680: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f690: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f6a0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f6b0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f6c0: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f6d0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f6e0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f6f0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f700: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f710: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f720: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f730: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f740: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f750: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f760: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f770: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f780: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f790: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f7a0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
f7b0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
f7c0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
f7d0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
f7e0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
f800: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
f810: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
f820: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
f830: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
f840: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
f850: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
f860: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f870: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
f880: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
f890: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
f8a0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
f8b0: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
f8c0: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
f8d0: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
f8e0: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
f8f0: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
f900: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
f910: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
f920: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
f930: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
f940: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f950: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
f960: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
f970: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
f980: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
f990: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
f9a0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
f9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
f9c0: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
f9d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
f9e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f9f0: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
fa00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fa10: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
fa20: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
fa30: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
fa40: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
fa50: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
fa60: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
fa70: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
fa80: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
fa90: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
faa0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
fab0: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fac0: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fad0: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fae0: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
faf0: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fb10: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fb20: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fb30: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fb40: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fb50: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
fb60: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fb70: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fb80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fb90: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fba0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
fbb0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fbc0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fbd0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fbe0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fc00: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fc10: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fc20: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fc30: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fc40: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fc50: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
fc60: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fc70: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fc80: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fc90: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
fca0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
fcb0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
fcc0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
fcd0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
fce0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
fcf0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
fd00: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
fd10: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
fd20: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
fd30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
fd40: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
fd50: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
fd60: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
fd70: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
fd80: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
fd90: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fda0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
fdb0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
fdc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
fdd0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
fde0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
fdf0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fe00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fe10: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
fe20: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
fe30: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fe40: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
fe50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
fe60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
fe70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
fe80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
fe90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
fea0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
feb0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
fec0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
fed0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
fee0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
fef0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
ff00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
ff10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
ff20: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
ff30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ff40: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
ff50: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
ff60: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
ff70: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
ff80: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
ff90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ffa0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
ffb0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
ffc0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
ffd0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ffe0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
fff0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10000 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10010 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10020 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10030 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10040 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10050 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10060 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
10070 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10080 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
10090 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
100a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
100b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
100c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
100d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
100e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
100f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10100 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10110 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10120 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10130 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10140 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
10150 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
10160 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
10170 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
10180 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
10190 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
101a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
101b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
101c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
101d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
101e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
101f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10200 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10210 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10220 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10230 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10240 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
10250 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
10260 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10270 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
10280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10290 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
102a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
102b0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
102c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
102d0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
102e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
102f0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10300 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10310 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10320 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10330 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10340 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10350 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10360 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10370 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
10380 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
10390 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
103a0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
103b0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
103c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
103d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
103e0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
103f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10400 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10410 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10420 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10440 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10450 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
10460 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
10470 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
10480 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
10490 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
104a0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
104b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
104c0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
104d0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
104e0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
104f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10510 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10520 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10530 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10540 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10550 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10560 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10570 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10580 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10590 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
105a0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
105b0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
105c0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
105d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
105e0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
105f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10600 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10610 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10620 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10630 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10640 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10650 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10660 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
10670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10680 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
10690 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
106a0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
106b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
106c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
106d0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
106e0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
106f0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10700 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10710 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10720 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10730 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10740 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
10750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10760 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
10770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10780 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
10790 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
107a0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
107b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
107c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
107d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
107e0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
107f0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10800 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10810 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10830 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10840 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10850 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
10860 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
10870 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
10880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10890 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
108a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
108b0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
108c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
108d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
108e0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
108f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10900 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10910 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10920 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10930 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10940 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10950 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10960 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
10970 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
10980 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10990 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
109a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
109b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
109c0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
109d0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
109e0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
109f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10a00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10a20 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10a30 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10a50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10a60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10a70 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10a80 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10a90 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10aa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10ab0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10ac0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10ad0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10ae0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10af0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10b10 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10b20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10b30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10b40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10b50 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10b60 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10b70 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10b80 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10ba0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10bb0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10bd0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10be0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10c00 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10c20 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10c30 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10c40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10c50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10c60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10c70 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10c80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10c90 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10ca0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10cb0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10cc0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10cd0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10ce0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10cf0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10d00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10d10 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10d20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10d30 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10d40 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10d50 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10d60 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10d70 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10d80 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10d90 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10da0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
10db0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
10dc0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
10dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10de0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
10df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10e00 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
10e10 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10e20 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
10e30 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
10e40 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
10e50 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
10e60 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
10e70 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
10e80 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
10e90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10ea0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
10eb0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
10ec0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10ed0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
10ee0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
10ef0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
10f00 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
10f10 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
10f20 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
10f30 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
10f40 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
10f50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
10f60 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
10f70 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
10f80 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
10f90 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
10fa0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
10fb0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
10fc0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
10fd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10fe0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
10ff0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11000 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11010 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11020 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11030 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11040 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
11050 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
11060 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
11070 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11080 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
11090 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
110a0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
110b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
110c0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
110d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
110e0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
110f0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11100 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11110 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11120 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11130 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11140 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
11150 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
11160 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
11170 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
11180 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
11190 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
111a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
111b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
111c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
111d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
111e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
111f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11200 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11210 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11220 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11230 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11240 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11250 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
11260 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
11270 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
11280 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
11290 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
112a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
112b0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
112c0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
112d0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
112e0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
112f0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11300 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11310 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11320 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11330 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11340 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
11350 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
11360 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
11370 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
11380 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
11390 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
113a0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
113b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
113c0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
113d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
113e0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
113f0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11400 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11410 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11420 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11430 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11440 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11460 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
11470 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11480 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11490 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
114a0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
114b0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
114c0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
114d0 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
114e0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
114f0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11500 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11510 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11520 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11530 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11540 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
11550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
11560 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
11570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
11580 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
11590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
115a0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
115b0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
115c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
115d0 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
115e0 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
115f0 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11600 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11610 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11620 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11630 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11640 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
11650 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
11660 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
11670 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
11680 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
11690 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
116a0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
116b0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
116c0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
116d0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
116e0 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
116f0 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11700 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11710 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11720 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11730 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11740 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
11750 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
11760 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
11770 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
11780 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
11790 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
117a0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
117b0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
117c0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
117d0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
117e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
117f0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11810 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11820 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11830 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11840 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11850 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
11860 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
11870 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
11880 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
11890 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
118a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
118b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
118c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
118d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
118e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
118f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11900 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11920 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11930 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11940 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11950 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
11960 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
11970 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
11980 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
11990 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
119a0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
119b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
119c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
119d0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
119e0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
119f0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11a00 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11a10 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11a20 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11a40 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11a50 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
11a60 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
11a70 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
11a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11a90 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
11aa0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11ab0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11ac0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11ad0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11ae0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11af0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11b00 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11b10 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11b20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11b30 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11b40 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11b50 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11b60 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11b70 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11b80 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11ba0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11bb0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11bc0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11bd0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11be0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11bf0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11c00 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11c10 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11c20 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11c30 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11c40 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11c60 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11c70 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11c80 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11c90 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11ca0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11cb0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11cc0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11cd0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11ce0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11cf0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11d00 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11d10 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11d20 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11d30 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11d40 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11d50 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11d60 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11d70 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11d80 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11d90 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11da0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
11db0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11dc0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
11dd0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
11de0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
11df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11e00 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11e10 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
11e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11e30 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11e50 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11e60 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11e80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11e90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11ea0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
11eb0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
11ec0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
11ed0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
11ee0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11ef0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
11f00 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
11f10 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
11f20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
11f30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
11f40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
11f50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11f60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11f70 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
11f80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11f90 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
11fa0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
11fb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11fc0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11fd0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11fe0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11ff0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12000 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12010 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12020 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12030 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12040 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
12050 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
12060 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
12070 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12080 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
12090 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
120a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
120b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
120c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
120d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
120e0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
120f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12100 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12110 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12120 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12130 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12140 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12150 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12160 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12170 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12180 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
12190 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
121a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
121b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
121c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
121d0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
121e0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
121f0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12200 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12210 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12220 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12230 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12240 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
12250 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
12260 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
12270 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
12280 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
12290 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
122a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
122b0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
122c0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
122d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
122e0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
122f0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12300 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12310 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12320 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12330 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12340 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12350 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12360 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12370 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
12380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12390 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
123a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
123b0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
123c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
123d0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
123e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
123f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12400 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12410 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12420 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12430 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12450 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
12460 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
12470 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
12480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12490 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
124a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
124b0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
124c0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
124d0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
124e0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
124f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12500 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12510 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12520 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12530 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12540 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
12550 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
12560 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
12570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12580 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
12590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
125b0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
125c0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
125d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
125e0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
125f0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12600 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12610 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12620 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12630 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12640 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12670 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12680 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
12690 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
126a0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
126b0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
126c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
126d0 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
126e0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
126f0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12700 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12710 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12720 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12730 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12750 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12770 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
12780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12790 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
127a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
127b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
127c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
127d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
127e0 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
127f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12800 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12810 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12820 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12830 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12840 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12850 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
12860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12870 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
12880 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
12890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
128a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
128b0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
128c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
128d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
128e0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
128f0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12900 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12910 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12920 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12930 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12940 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12950 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
12960 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
12970 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
12980 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
12990 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
129a0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
129b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
129c0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
129d0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
129e0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
129f0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12a00 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12a10 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12a20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12a40 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12a50 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
12a60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12a70 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
12a80 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
12a90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
12aa0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
12ab0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12ac0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12ad0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12ae0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12af0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12b00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12b10 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12b20 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12b30 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12b40 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12b50 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12b60 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12b70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12b80 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12b90 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12ba0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12bb0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12bc0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12bd0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12be0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12bf0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12c00 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12c10 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12c20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12c30 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12c40 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12c50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12c60 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12c70 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12c80 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12c90 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12cb0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12cc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12cd0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12d00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12d10 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12d20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12d30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12d40 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12d50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12d60 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12d70 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12d80 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12d90 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12da0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
12db0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
12dc0 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
12dd0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12de0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
12df0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
12e00 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
12e10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
12e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
12e30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
12e40 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
12e50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
12e60 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
12e70 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
12e80 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
12e90 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
12ea0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
12eb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
12ec0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
12ed0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
12ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
12ef0 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
12f00 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
12f10 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
12f20 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
12f30 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
12f40 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
12f50 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
12f60 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
12f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
12f80 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
12f90 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
12fa0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
12fb0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
12fc0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
12fd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
12fe0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
12ff0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13000 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13010 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13030 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
13040 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
13050 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
13060 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
13070 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
13080 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
13090 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
130a0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
130b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
130c0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
130d0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
130e0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
130f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13100 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
13110 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
13120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13130 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13140 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
13150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13160 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
13170 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
13180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13190 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
131a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
131b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
131c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
131d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
131e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
131f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
13200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13210 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
13220 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
13230 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
13240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13250 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
13260 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
13270 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
13280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13290 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
132a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
132b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
132c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
132d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
132e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
132f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
13300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13310 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13320 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
13330 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13350 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
13360 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
13370 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13390 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
133a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
133b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
133c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
133d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
133e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
133f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
13400 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
13410 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13420 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
13430 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
13440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13450 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
13460 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
13470 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13480 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
13490 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
134a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
134b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
134c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
134d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
134e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
134f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
13500 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
13510 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13520 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
13530 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
13540 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
13550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13560 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13570 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
13580 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
13590 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  2* */../*.** CAP
135a0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
135b0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
135c0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
135d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
135e0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
135f0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13610 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13620 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
13630 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13640 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13660 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
13670 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
13680 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
13690 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
136a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
136b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
136c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
136d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
136e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
136f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
13700 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
13710 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
13720 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
13730 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
13740 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
13750 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
13760 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
13770 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13780 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
13790 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
137a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
137b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
137c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
137d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
137e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
137f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
13800 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
13810 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13820 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
13830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
13840 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
13850 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
13860 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
13870 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13880 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
13890 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
138a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
138b0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
138c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
138d0 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
138e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
138f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
13900 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
13910 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
13920 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
13930 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
13940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
13950 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
13960 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13970 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
13980 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
13990 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
139a0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
139b0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
139c0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
139d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
139e0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
139f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
13a00 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13a10 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13a20 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
13a30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
13a40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13a50 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
13a60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
13a70 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
13a80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13a90 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
13aa0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
13ab0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
13ac0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
13ad0 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
13ae0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
13af0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
13b00 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
13b10 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
13b20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
13b30 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
13b40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
13b50 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
13b60 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
13b70 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
13b80 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
13b90 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
13ba0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
13bb0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
13bc0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13bd0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
13be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
13bf0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
13c00 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
13c10 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
13c20 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
13c30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
13c40 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
13c50 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
13c60 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
13c70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
13c80 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
13c90 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
13ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
13cb0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
13cc0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
13cd0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13ce0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
13cf0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
13d00 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
13d10 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
13d20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
13d30 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
13d40 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
13d50 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
13d60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
13d70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
13d80 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
13d90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
13da0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
13db0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
13dc0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
13dd0 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
13de0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
13df0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
13e00 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
13e10 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
13e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13e30 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
13e40 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
13e50 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
13e60 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
13e70 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
13e80 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
13e90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13ea0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
13eb0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
13ec0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13ed0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
13ee0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
13ef0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
13f00 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
13f10 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
13f20 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
13f30 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
13f40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
13f50 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
13f60 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
13f70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
13f80 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
13f90 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
13fa0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
13fb0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
13fc0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
13fd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
13fe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
13ff0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
14000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
14010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
14020 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
14030 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
14040 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
14050 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
14060 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
14070 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
14080 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
14090 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
140a0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
140b0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
140c0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
140d0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
140e0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
140f0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
14100 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
14110 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
14120 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14130 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
14140 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
14150 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
14160 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
14170 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
14180 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
14190 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
141a0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
141b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
141c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
141d0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
141e0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
141f0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
14200 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
14210 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
14220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14230 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
14240 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
14250 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
14260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14270 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
14280 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
14290 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
142a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
142b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
142c0 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
142d0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
142e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
142f0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
14300 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
14310 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
14320 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
14330 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
14340 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
14350 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
14360 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
14370 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
14380 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
14390 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
143a0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
143b0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
143c0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
143d0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
143e0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
143f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
14400 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14410 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
14420 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
14430 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
14440 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
14450 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
14460 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
14470 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
14480 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
14490 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
144a0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
144b0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
144c0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
144d0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
144e0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
144f0 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
14500 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
14510 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
14520 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
14530 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
14540 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
14550 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
14560 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
14570 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
14580 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
14590 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
145a0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
145b0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
145c0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
145d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
145e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
145f0 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
14600 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
14610 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
14620 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
14630 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
14640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
14650 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
14660 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
14670 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
14680 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
14690 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
146a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
146b0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
146c0 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
146d0 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
146e0 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
146f0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14700 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
14710 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
14720 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
14730 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
14740 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
14750 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
14760 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
14770 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
14780 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
14790 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
147a0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
147b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
147c0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
147d0 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
147e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
147f0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14800 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
14810 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
14820 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
14830 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14840 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
14850 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14860 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
14870 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
14880 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
14890 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
148a0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
148b0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
148c0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
148d0 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
148e0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
148f0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
14900 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
14910 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14920 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
14930 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
14940 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
14950 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
14960 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
14970 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
14980 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
14990 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
149a0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
149b0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
149c0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
149d0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
149e0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
149f0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
14a00 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
14a10 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
14a20 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
14a30 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
14a40 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
14a50 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
14a60 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
14a70 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
14a80 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
14a90 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
14aa0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
14ab0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
14ac0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
14ad0 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
14ae0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
14af0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
14b00 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
14b10 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
14b20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
14b30 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
14b40 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
14b50 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
14b60 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
14b70 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
14b80 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
14b90 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
14ba0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
14bb0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
14bc0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
14bd0 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
14be0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
14bf0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
14c00 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
14c10 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
14c20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
14c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14c40 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
14c50 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14c60 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
14c70 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
14c80 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
14c90 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
14ca0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
14cb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14cc0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14cd0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
14ce0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
14cf0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
14d00 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
14d10 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
14d20 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
14d30 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
14d40 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
14d50 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
14d60 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14d70 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
14d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14d90 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
14da0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
14db0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
14dc0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
14de0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
14df0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
14e00 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
14e10 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
14e20 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
14e30 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
14e40 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
14e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14e60 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
14e70 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
14e80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
14e90 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
14ea0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
14eb0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
14ec0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
14ed0 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
14ee0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
14ef0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
14f00 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
14f10 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
14f20 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
14f30 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
14f40 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
14f50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
14f60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
14f70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
14f80 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
14f90 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
14fa0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
14fb0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
14fc0 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
14fd0 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
14fe0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
14ff0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
15000 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
15010 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
15020 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
15030 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
15040 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
15050 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
15060 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
15070 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
15080 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
15090 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
150a0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
150b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
150c0 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
150d0 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
150e0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
150f0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
15100 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
15110 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
15120 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
15130 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
15140 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
15150 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
15160 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
15170 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
15180 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
15190 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
151a0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
151b0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
151c0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
151d0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
151e0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
151f0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
15200 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15210 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
15220 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
15230 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
15240 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
15250 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
15260 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
15270 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
15280 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
15290 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
152a0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
152b0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
152c0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
152d0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
152e0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
152f0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
15300 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
15310 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
15320 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
15330 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
15340 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
15350 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
15360 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
15370 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
15380 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
15390 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
153a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
153b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
153c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
153d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
153e0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
153f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15400 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
15410 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
15420 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
15430 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
15440 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
15450 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
15460 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
15470 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
15480 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
15490 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
154a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
154b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
154c0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
154d0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
154e0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
154f0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
15500 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
15510 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
15520 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
15530 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
15540 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
15550 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
15560 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
15570 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
15580 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
15590 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
155a0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
155b0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
155c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
155d0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
155e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
155f0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
15600 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
15610 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
15620 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
15630 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
15640 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
15650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
15660 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
15670 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
15680 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
15690 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
156a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
156b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
156c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
156d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
156e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
156f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
15700 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
15710 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
15720 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
15730 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
15740 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15750 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
15760 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15770 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
15780 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
15790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
157a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
157b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
157c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
157d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
157e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
157f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
15800 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
15810 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
15820 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
15830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
15850 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
15860 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
15870 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
15880 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
15890 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
158a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
158b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
158c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
158d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
158e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
158f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
15900 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
15910 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
15920 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
15930 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
15940 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15950 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
15960 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
15970 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
15980 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
15990 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
159a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
159b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
159c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
159d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
159e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
159f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
15a00 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
15a10 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
15a20 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
15a30 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
15a40 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
15a50 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15a60 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
15a70 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
15a80 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
15a90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
15aa0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
15ab0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
15ac0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
15ad0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
15ae0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
15af0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
15b00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
15b10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
15b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
15b30 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
15b40 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
15b50 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
15b60 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
15b70 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
15b80 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15b90 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15ba0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
15bb0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
15bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15bd0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
15be0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15bf0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
15c00 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
15c10 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
15c20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15c30 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
15c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15c50 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
15c60 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
15c70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15c80 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
15c90 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
15ca0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
15cb0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
15cc0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
15cd0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
15ce0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
15cf0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
15d00 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
15d10 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
15d20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
15d30 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
15d40 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
15d50 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
15d60 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
15d70 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
15d80 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
15d90 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
15da0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
15db0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
15dc0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
15dd0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
15de0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
15df0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
15e00 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
15e10 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
15e20 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
15e30 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
15e40 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
15e50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
15e60 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
15e70 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
15e80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
15e90 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
15ea0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
15eb0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
15ec0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
15ed0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
15ee0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
15ef0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
15f00 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
15f10 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
15f20 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
15f30 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
15f40 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
15f50 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
15f60 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
15f70 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
15f80 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
15f90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
15fa0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
15fb0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
15fc0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
15fd0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
15fe0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
15ff0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
16000 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
16010 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16020 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
16030 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
16040 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
16050 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
16060 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
16070 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
16080 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
16090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
160a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
160b0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
160c0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
160d0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
160e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
160f0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
16100 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
16110 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
16120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
16130 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
16140 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
16150 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16160 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
16170 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
16180 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
16190 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
161a0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
161b0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
161c0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
161d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
161e0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
161f0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
16200 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
16210 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
16220 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
16230 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
16240 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
16250 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
16260 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
16270 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
16280 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
16290 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
162a0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
162b0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
162c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
162d0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
162e0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
162f0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
16300 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
16310 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
16320 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16330 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
16340 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
16350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16360 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
16370 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
16380 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
16390 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
163a0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
163b0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
163c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
163d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
163e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
163f0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
16400 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
16410 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
16420 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
16430 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
16440 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
16450 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
16460 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
16470 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
16480 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
16490 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
164a0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
164b0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
164c0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
164d0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
164e0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
164f0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
16500 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
16510 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
16520 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
16530 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
16540 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
16550 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
16560 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
16570 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
16580 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
16590 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
165a0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
165b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
165c0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
165d0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
165e0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
165f0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
16600 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
16610 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
16620 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
16630 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
16640 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
16650 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
16660 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
16670 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
16680 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
16690 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
166a0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
166b0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
166c0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
166d0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
166e0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
166f0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
16700 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
16710 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
16720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
16730 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
16740 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
16750 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
16760 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
16770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16780 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
16790 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
167a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
167b0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
167c0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
167d0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
167e0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
167f0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
16800 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
16810 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
16820 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
16830 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
16840 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
16850 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
16860 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
16870 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
16880 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
16890 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
168a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
168b0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
168c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
168d0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
168e0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
168f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
16900 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
16910 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
16920 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
16930 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
16940 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
16950 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
16960 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
16970 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
16980 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
16990 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
169a0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
169b0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
169c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
169d0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
169e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
169f0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
16a00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
16a10 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
16a20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
16a30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
16a40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16a50 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
16a60 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
16a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
16a80 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
16a90 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
16aa0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
16ab0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
16ac0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
16ad0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
16ae0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
16af0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
16b00 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
16b10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
16b20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
16b30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
16b40 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
16b50 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
16b60 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
16b70 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
16b80 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
16b90 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
16ba0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
16bb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16bc0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16bd0 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
16be0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
16bf0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
16c00 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
16c10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
16c20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
16c30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
16c40 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
16c50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
16c60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
16c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
16c80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
16c90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
16ca0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
16cb0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
16cc0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
16cd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
16ce0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
16cf0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
16d00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
16d10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
16d20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
16d30 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
16d40 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
16d50 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
16d60 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
16d70 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
16d80 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
16d90 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
16da0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
16db0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
16dc0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
16dd0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
16de0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
16df0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
16e00 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16e10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
16e20 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
16e30 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
16e40 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
16e50 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
16e60 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
16e70 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
16e80 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
16e90 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
16ea0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
16eb0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
16ec0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
16ed0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
16ee0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
16ef0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
16f00 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
16f10 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
16f20 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
16f30 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
16f40 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
16f50 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
16f60 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
16f70 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
16f80 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
16f90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16fa0 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
16fb0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
16fc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
16fd0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
16fe0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
16ff0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
17000 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
17010 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
17020 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
17030 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
17040 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
17050 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
17060 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
17070 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
17080 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
17090 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
170a0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
170b0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
170c0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
170d0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
170e0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
170f0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
17100 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
17110 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
17120 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
17130 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
17140 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
17150 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
17160 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
17170 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
17180 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
17190 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
171a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
171b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
171c0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
171d0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
171e0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
171f0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
17200 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
17210 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
17220 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
17230 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
17240 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
17250 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
17260 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
17270 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
17280 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
17290 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
172a0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
172b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
172c0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
172d0 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
172e0 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
172f0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
17300 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
17310 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
17320 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
17330 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
17340 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
17350 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
17360 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17370 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
17380 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
17390 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
173a0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
173b0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
173c0 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
173d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
173e0 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
173f0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
17400 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
17410 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
17420 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
17430 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
17440 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
17450 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
17460 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
17470 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
17480 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
17490 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
174a0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
174b0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
174c0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
174d0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
174e0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
174f0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
17500 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
17510 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
17520 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
17530 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
17540 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
17550 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
17560 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
17570 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
17580 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
17590 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
175a0 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
175b0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
175c0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
175d0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
175e0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
175f0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
17600 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
17610 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
17620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17630 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
17640 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
17650 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
17660 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
17670 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
17680 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
17690 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
176a0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
176b0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
176c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
176d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
176e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
176f0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
17700 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
17710 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
17720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17730 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17740 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
17750 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
17760 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
17770 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
17780 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
17790 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
177a0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
177c0 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
177d0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
177e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
177f0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
17800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
17810 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
17820 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
17830 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
17840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17850 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
17860 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
17870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
17880 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
17890 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
178a0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
178b0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
178c0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
178d0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
178e0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
178f0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
17900 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
17910 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
17920 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
17930 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
17940 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
17950 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
17960 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
17970 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
17980 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
17990 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
179a0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
179b0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
179c0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
179d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
179e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
179f0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
17a00 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
17a10 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
17a20 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
17a30 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
17a40 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
17a50 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
17a60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17a70 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17a80 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17a90 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
17aa0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
17ab0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
17ac0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
17ad0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
17ae0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
17af0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
17b00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
17b10 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
17b20 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
17b30 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
17b40 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
17b50 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
17b60 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
17b70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
17b80 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
17b90 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
17ba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17bb0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
17bc0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
17bd0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
17be0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
17bf0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17c00 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17c10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17c20 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17c30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17c40 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
17c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
17c60 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
17c70 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
17c80 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
17c90 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
17ca0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17cb0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
17cc0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
17cd0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
17ce0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
17cf0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17d00 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17d10 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17d20 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17d30 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17d40 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
17d50 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
17d60 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
17d70 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
17d80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
17d90 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
17da0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
17db0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
17dc0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
17dd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
17de0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
17df0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17e00 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17e10 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17e20 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17e30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17e40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
17e50 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
17e60 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
17e70 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
17e80 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
17e90 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
17ea0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17eb0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
17ec0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
17ed0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
17ee0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
17ef0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17f00 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17f10 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17f20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17f30 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17f40 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
17f50 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
17f60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17f70 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
17f80 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
17f90 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
17fa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
17fb0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
17fc0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
17fd0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
17fe0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
17ff0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
18000 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
18010 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
18020 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
18030 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
18040 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
18050 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
18060 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
18070 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
18080 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
18090 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
180a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
180b0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
180c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
180d0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
180e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
180f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
18100 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
18110 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
18120 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18130 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
18140 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
18150 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
18160 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
18170 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
18180 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
18190 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
181a0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
181b0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
181c0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
181d0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
181e0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
181f0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
18200 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
18210 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
18220 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
18230 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
18240 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
18250 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
18260 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
18270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18280 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18290 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
182a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
182b0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
182c0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
182d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
182e0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
182f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
18300 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
18310 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18320 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
18330 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18340 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
18350 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18360 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
18370 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
18380 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
18390 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
183a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
183b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
183c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
183d0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
183e0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
183f0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
18400 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
18410 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
18420 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
18430 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
18440 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
18450 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
18460 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
18470 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
18480 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
18490 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
184a0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
184b0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
184c0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
184d0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
184e0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
184f0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
18500 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
18510 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
18520 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
18530 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
18540 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
18550 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
18560 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
18570 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
18580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18590 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
185a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
185b0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
185c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
185d0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
185e0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
185f0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18600 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18610 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18620 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18630 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18640 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
18650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18660 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
18670 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
18680 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
18690 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
186a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
186b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
186c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
186d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
186e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
186f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18700 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18710 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18720 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18730 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18740 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
18750 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
18760 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
18770 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
18780 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
18790 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
187a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
187b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
187c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
187d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
187e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
187f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18800 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18810 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
18820 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18830 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
18840 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
18850 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
18860 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18870 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
18880 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
18890 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
188a0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
188b0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
188c0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
188d0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
188e0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
188f0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
18900 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
18910 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
18920 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
18930 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
18940 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
18950 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
18960 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
18970 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
18990 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
189a0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
189b0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
189c0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
189d0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
189e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
189f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18a00 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
18a10 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
18a20 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
18a30 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
18a40 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
18a50 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
18a60 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18a70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
18a80 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
18a90 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
18aa0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
18ab0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
18ac0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
18ad0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
18ae0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
18af0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
18b00 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
18b10 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
18b20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
18b30 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
18b40 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
18b50 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
18b60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
18b70 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
18b80 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
18b90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
18ba0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
18bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
18bc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
18bd0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
18be0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
18bf0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
18c00 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
18c10 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
18c20 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
18c30 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
18c40 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
18c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18c60 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
18c70 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
18c80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
18c90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
18ca0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
18cb0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
18cc0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
18cd0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
18ce0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
18cf0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
18d00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
18d10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
18d20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
18d30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
18d40 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
18d50 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
18d60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18d70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
18d80 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
18d90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
18da0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
18db0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
18dc0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18dd0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
18de0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
18df0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
18e00 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
18e10 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
18e20 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
18e30 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
18e40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
18e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
18e60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
18e70 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
18e80 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
18e90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
18ea0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
18eb0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
18ec0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
18ed0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
18ee0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
18ef0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
18f00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
18f10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
18f20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
18f30 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
18f40 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
18f50 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
18f60 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
18f70 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
18f80 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
18f90 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
18fa0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
18fb0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
18fc0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
18fd0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
18fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
18ff0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
19000 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
19010 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
19020 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
19030 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19040 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
19050 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
19060 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
19070 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
19080 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
19090 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
190a0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
190b0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
190c0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
190d0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
190e0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
190f0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
19100 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
19110 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
19120 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
19130 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
19140 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
19150 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
19160 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
19170 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
19180 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
19190 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
191a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
191b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
191c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
191d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
191e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
191f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
19200 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
19210 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
19220 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
19230 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
19240 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
19250 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
19260 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
19270 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
19280 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
19290 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
192a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
192b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
192c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
192d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
192e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
192f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19300 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
19310 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
19320 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
19330 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
19340 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
19350 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
19360 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
19370 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
19380 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
19390 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
193a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
193b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
193c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
193d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
193e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
193f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
19400 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
19410 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
19420 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
19430 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
19440 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
19450 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
19460 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
19470 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19480 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
19490 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
194a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
194b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
194c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
194d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
194e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
194f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
19500 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
19510 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
19520 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
19530 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
19540 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
19550 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
19560 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
19570 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
19580 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19590 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
195a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
195b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
195c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
195d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
195e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
195f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
19600 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
19610 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
19620 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
19630 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
19640 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19650 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
19660 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
19670 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
19680 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
19690 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
196a0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
196b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
196c0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
196d0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
196e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
196f0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
19700 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
19710 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
19720 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
19730 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
19740 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
19750 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19760 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
19770 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
19780 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
19790 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
197a0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
197b0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
197c0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
197d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
197e0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
197f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19800 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
19810 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
19820 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
19830 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
19840 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
19850 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
19860 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
19870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
19880 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
19890 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
198a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
198b0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
198c0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
198d0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
198e0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
198f0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
19900 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
19910 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
19920 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
19930 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
19940 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
19950 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
19960 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
19970 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
19980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
19990 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
199a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
199b0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
199c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
199d0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
199e0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
199f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
19a00 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
19a10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
19a20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
19a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
19a50 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
19a60 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
19a70 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
19a80 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
19a90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
19aa0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
19ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
19ac0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
19ad0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
19ae0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
19af0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
19b00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
19b10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
19b20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
19b30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
19b40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
19b50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
19b60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
19b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19b80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
19b90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
19ba0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
19bb0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
19bc0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
19bd0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
19be0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
19bf0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
19c00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
19c10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
19c20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
19c30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
19c40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
19c50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
19c60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
19c70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
19c80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
19c90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
19ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
19cb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
19cc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
19cd0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
19ce0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
19cf0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
19d00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
19d10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19d20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
19d30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
19d40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
19d50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
19d60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
19d70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
19d80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
19d90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
19da0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
19db0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
19dc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
19dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
19de0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
19df0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
19e00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
19e10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
19e20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
19e30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
19e40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
19e50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
19e60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
19e70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
19e80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
19e90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
19ea0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
19eb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
19ec0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
19ed0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
19ee0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
19ef0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
19f00 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
19f10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
19f20 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
19f30 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
19f40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
19f50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19f60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
19f70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19f80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
19f90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
19fa0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
19fb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
19fc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
19fd0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
19fe0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
19ff0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1a000 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1a010 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1a020 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1a030 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1a040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a050 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1a060 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1a070 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1a080 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1a090 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1a0a0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1a0b0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1a0c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1a0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1a0e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1a0f0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1a100 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1a110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a120 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1a130 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1a140 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1a150 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1a160 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1a170 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1a180 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1a190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1a1a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1a1b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1a1c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1a1d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1a1e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1a1f0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1a200 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1a210 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1a220 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1a230 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1a240 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1a250 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1a260 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1a270 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1a280 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1a290 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1a2a0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1a2b0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1a2c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1a2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a2e0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1a2f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1a300 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1a310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1a320 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1a330 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a340 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1a350 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1a360 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1a370 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1a380 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1a390 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1a3a0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1a3b0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1a3c0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1a3d0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1a3e0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1a3f0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1a400 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1a410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1a420 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1a430 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1a440 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1a450 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1a460 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1a470 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1a480 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1a490 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1a4a0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1a4b0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1a4c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1a4d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1a4e0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1a4f0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1a500 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1a510 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1a520 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1a530 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1a540 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1a550 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1a560 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1a570 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1a580 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1a590 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1a5a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1a5b0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1a5c0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1a5d0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1a5e0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1a5f0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1a600 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1a610 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1a620 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1a630 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1a640 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1a650 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1a660 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1a670 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1a680 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1a690 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1a6a0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1a6b0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1a6c0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1a6d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1a6e0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1a6f0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1a700 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1a710 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1a720 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1a730 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1a740 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1a750 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1a760 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1a770 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1a780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a790 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1a7a0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1a7b0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1a7c0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1a7d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1a7e0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1a7f0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1a800 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1a810 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1a820 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1a830 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1a840 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1a850 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a860 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1a870 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1a880 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1a890 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1a8a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a8b0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1a8c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1a8d0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1a8e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a8f0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1a900 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1a910 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1a920 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1a930 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1a940 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1a950 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1a960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a970 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1a980 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1a990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1a9a0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1a9b0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1a9c0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1a9d0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1a9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1a9f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1aa00 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1aa10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1aa20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1aa30 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1aa40 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1aa50 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1aa60 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1aa70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1aa80 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1aa90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1aaa0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1aab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1aac0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1aad0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1aae0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1aaf0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1ab00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1ab10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ab20 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1ab30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ab40 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1ab50 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1ab60 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1ab70 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1ab80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1ab90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1aba0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1abb0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1abc0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1abd0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1abe0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1abf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ac00 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1ac10 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1ac20 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1ac30 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1ac40 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1ac50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1ac60 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1ac70 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1ac80 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1ac90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1aca0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1acb0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1acc0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1acd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ace0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1acf0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ad00 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1ad10 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1ad20 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1ad30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1ad40 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1ad50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1ad60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ad70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ad80 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1ad90 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1ada0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1adb0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1adc0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1add0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1ade0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1adf0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1ae00 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1ae10 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1ae20 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1ae30 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1ae40 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1ae50 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1ae60 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1ae70 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1ae80 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1ae90 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1aea0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1aeb0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1aec0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1aed0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1aee0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1aef0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1af00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1af10 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1af20 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1af30 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1af40 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1af50 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1af60 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1af70 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1af80 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1af90 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1afa0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1afb0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1afc0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1afd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1afe0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1aff0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1b000 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1b010 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1b020 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1b030 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b040 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1b050 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1b060 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1b070 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1b080 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1b090 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1b0a0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1b0b0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1b0c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1b0d0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1b0e0 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  thod..*/.SQLITE_
1b0f0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1b100 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1b110 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1b120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1b130 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1b140 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1b150 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1b160 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1b170 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1b180 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1b190 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1b1a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b1b0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1b1c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1b1d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1b1e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b1f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1b200 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1b210 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1b220 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1b230 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1b240 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1b250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b260 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1b270 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1b280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1b290 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1b2a0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1b2b0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1b2c0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1b2d0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1b2e0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1b2f0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1b300 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1b310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b320 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1b330 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1b340 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1b350 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1b360 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1b370 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1b380 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1b390 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1b3a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1b3b0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1b3c0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1b3d0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1b3e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1b3f0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1b400 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1b410 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1b420 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1b430 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1b440 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1b450 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1b460 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1b470 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1b480 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1b490 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1b4a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1b4b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1b4c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1b4d0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1b4e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b4f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1b500 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1b510 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1b520 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1b530 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1b540 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1b550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b560 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1b570 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1b580 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1b590 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1b5a0 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1b5b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b5c0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1b5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1b5e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1b5f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1b600 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1b610 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1b620 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1b630 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1b640 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1b650 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1b660 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1b670 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1b680 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b690 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1b6a0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1b6b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1b6c0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1b6d0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1b6e0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1b6f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1b700 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b710 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1b720 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1b730 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1b740 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1b750 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1b760 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b770 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1b780 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1b790 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1b7a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1b7b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b7c0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1b7d0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1b7e0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1b7f0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1b800 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1b810 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b820 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b830 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1b840 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b850 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1b860 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1b870 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1b880 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1b890 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1b8a0 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1b8b0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1b8c0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1b8d0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1b8e0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1b8f0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1b900 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1b910 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1b920 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1b930 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1b940 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1b950 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1b960 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1b970 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1b980 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1b990 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1b9a0 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1b9b0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1b9c0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1b9d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1b9e0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1b9f0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1ba00 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1ba10 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1ba20 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1ba30 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1ba40 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1ba50 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1ba60 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1ba70 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1ba80 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1ba90 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1baa0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1bab0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1bac0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1bad0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1bae0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1baf0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1bb00 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1bb10 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1bb20 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1bb30 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1bb40 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1bb50 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1bb60 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1bb70 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1bb80 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1bb90 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1bba0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1bbb0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1bbc0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1bbd0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1bbe0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1bbf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1bc00 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1bc10 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1bc20 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1bc30 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1bc40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1bc50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1bc60 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1bc70 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1bc80 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1bc90 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1bca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bcb0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1bcc0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1bcd0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1bce0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1bcf0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1bd00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1bd10 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1bd20 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1bd30 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1bd40 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1bd50 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1bd60 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1bd70 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1bd80 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1bd90 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1bda0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1bdb0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1bdc0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1bdd0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1bde0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1bdf0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1be00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1be10 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1be20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1be30 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1be40 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1be50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1be60 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1be70 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1be80 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1be90 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1bea0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1beb0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1bec0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1bed0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1bee0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1bef0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1bf00 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1bf10 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1bf20 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1bf30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1bf40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1bf50 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1bf60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1bf70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1bf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1bf90 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1bfa0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1bfb0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bfd0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1bfe0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1bff0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1c000 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1c010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c020 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1c030 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1c040 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1c050 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1c060 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1c070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1c080 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1c090 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1c0a0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1c0b0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1c0c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1c0d0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1c0e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1c0f0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1c100 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1c110 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1c120 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1c130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c140 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1c150 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1c160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1c170 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1c180 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1c190 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1c1a0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1c1b0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1c1c0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1c1d0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1c1e0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1c1f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1c200 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1c210 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1c220 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c230 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1c240 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1c250 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1c260 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
1c270 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c280 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1c290 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1c2a0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1c2b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1c2c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c2d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1c2e0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1c2f0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1c300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1c310 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1c320 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1c330 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c340 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1c350 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1c360 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1c370 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1c380 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1c390 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1c3a0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1c3b0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1c3c0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1c3d0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1c3e0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1c3f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c400 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1c410 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1c420 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1c430 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1c440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1c450 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1c460 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1c470 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1c480 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1c490 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1c4a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1c4b0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1c4c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1c4d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c4e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1c4f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1c500 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1c510 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1c520 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1c530 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1c540 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1c550 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1c560 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1c570 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1c580 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1c590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1c5a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c5b0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1c5c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1c5d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1c5e0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1c5f0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1c600 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1c610 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1c620 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1c640 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1c650 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1c660 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1c670 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1c680 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1c690 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1c6a0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1c6b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1c6c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c6d0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1c6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1c6f0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1c700 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1c710 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1c720 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1c730 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1c740 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1c750 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1c760 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1c770 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1c780 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1c790 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1c7a0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1c7b0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1c7c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1c7d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1c7e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1c7f0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1c800 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1c810 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1c820 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1c830 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1c840 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1c850 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1c860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c880 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1c890 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1c8a0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1c8b0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1c8c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1c8d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1c8e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1c8f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1c900 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1c910 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1c920 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1c930 2a 2a 2a 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 20 33 72 64 20 2a  ********** 3rd *
1c960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1c970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1c980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c990 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1c9a0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1c9b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1c9c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1c9d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c9e0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1c9f0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1ca00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ca10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ca20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ca30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ca40 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1ca50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ca60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ca70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ca80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1ca90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1caa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cac0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1cad0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1cae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1caf0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1cb00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cb10 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1cb20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1cb30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1cb40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1cb50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cb60 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1cb70 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1cb80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1cb90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1cba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1cbb0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1cbc0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1cbd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1cbe0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1cbf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cc00 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1cc10 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1cc20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cc30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cc40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cc50 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1cc60 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1cc70 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cc80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cc90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cca0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1ccb0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1ccc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ccd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ccf0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1cd00 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1cd10 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1cd20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cd30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cd40 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1cd50 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1cd60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1cd70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cd80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1cd90 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1cda0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1cdb0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1cdc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1cdd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1cde0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1cdf0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1ce00 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ce10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ce20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ce30 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1ce40 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1ce50 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1ce60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ce70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ce80 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ce90 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1cea0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ceb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1ced0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1cee0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1cef0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1cf00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cf10 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1cf20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1cf30 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1cf40 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1cf50 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1cf60 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1cf70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1cf80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1cf90 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1cfa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1cfb0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1cfc0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1cfd0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1cfe0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1cff0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d000 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1d010 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1d020 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1d030 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d040 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d050 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1d060 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1d070 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d080 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1d090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d0a0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1d0b0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1d0c0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1d0d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d0e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d0f0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1d100 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1d110 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1d120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d140 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1d150 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1d160 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1d170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d190 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1d1a0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1d1b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1d1c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d1d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d1e0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1d1f0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1d200 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d210 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d230 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1d240 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1d250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1d260 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1d270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d280 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1d290 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1d2a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1d2b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1d2c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1d2d0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1d2e0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1d2f0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1d300 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1d310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1d320 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1d330 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1d340 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1d350 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1d360 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1d370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d380 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1d390 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1d3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1d3b0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1d3c0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1d3d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d3e0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1d3f0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1d400 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1d410 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1d420 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1d430 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1d440 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1d450 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1d460 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1d470 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1d480 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1d490 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1d4a0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1d4b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1d4c0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1d4d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1d4e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1d4f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1d500 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1d510 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1d520 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1d530 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1d540 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1d550 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1d560 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1d570 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1d580 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1d590 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1d5a0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1d5b0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1d5c0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1d5d0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1d5e0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1d5f0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1d600 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1d610 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1d620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
1d630 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d640 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1d650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1d660 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1d670 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1d680 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1d690 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1d6a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1d6b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1d6c0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1d6d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1d6e0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1d6f0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1d700 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1d710 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1d720 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1d730 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1d740 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1d750 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1d760 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1d770 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1d780 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1d790 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1d7a0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1d7b0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1d7c0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1d7d0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1d7e0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1d7f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1d800 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1d810 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1d820 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1d830 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1d840 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1d850 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1d860 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1d870 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1d880 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1d890 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1d8a0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1d8b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
1d8c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1d8d0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1d8e0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1d8f0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1d900 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1d910 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
1d920 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1d930 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1d940 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1d950 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1d960 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1d970 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1d980 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1d990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1d9a0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1d9b0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1d9c0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1d9d0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1d9e0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1d9f0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1da00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1da10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1da20 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1da30 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1da40 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1da50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1da60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1da70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1da80 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1da90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1daa0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1dab0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1dac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1dad0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1dae0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1daf0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1db00 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1db10 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1db20 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1db30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1db40 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1db50 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1db60 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1db70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1db80 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1db90 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1dba0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1dbb0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1dbc0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1dbd0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1dbe0 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1dbf0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1dc00 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1dc10 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1dc20 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1dc30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dc40 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1dc50 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1dc60 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1dc70 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1dc80 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1dc90 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1dca0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1dcb0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1dcc0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1dcd0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1dce0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1dcf0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1dd00 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1dd10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1dd20 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1dd30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1dd40 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1dd50 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1dd60 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1dd70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1dd80 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1dd90 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1dda0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1ddb0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1ddc0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1ddd0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1dde0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1ddf0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1de00 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1de10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1de20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1de30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1de40 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1de50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1de60 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1de70 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1de80 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1de90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dea0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1deb0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1dec0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1ded0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
1dee0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1def0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1df00 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1df10 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1df20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1df30 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1df40 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1df50 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1df60 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1df70 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1df80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1df90 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1dfa0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1dfb0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1dfc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1dfd0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1dfe0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1dff0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1e000 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1e010 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1e020 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1e030 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1e040 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1e050 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1e060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e070 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1e080 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1e090 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1e0a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1e0b0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1e0c0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1e0d0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1e0e0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1e0f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1e100 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e110 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1e120 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1e130 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1e140 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1e150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1e160 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1e170 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1e180 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1e190 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1e1a0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1e1b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1e1c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1e1d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1e1e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1e1f0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1e200 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1e210 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1e220 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1e230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1e240 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1e250 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1e260 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1e270 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1e280 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1e290 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1e2a0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1e2b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1e2c0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1e2d0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1e2e0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1e2f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1e300 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1e310 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1e320 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1e330 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1e340 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1e350 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1e360 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1e370 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1e380 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1e390 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1e3a0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1e3b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1e3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e3d0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1e3e0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1e3f0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1e400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1e410 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1e420 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1e430 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1e440 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e450 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1e460 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1e470 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1e480 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1e490 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1e4a0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1e4b0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1e4c0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1e4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e4e0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1e4f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1e500 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e510 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1e520 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1e530 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1e540 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1e550 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1e560 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e570 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1e580 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1e590 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1e5a0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1e5b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1e5c0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1e5d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1e5e0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1e5f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1e600 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1e610 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1e620 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e630 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1e640 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1e650 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1e660 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1e670 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1e680 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e6a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1e6b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1e6c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1e6d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e6e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1e6f0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1e700 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1e710 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1e720 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1e730 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1e740 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1e750 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1e760 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1e770 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1e780 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1e790 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e7a0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1e7b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e7c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1e7d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1e7e0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1e7f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e800 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e810 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1e820 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1e830 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1e840 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1e850 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1e860 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1e870 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1e880 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1e890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1e8a0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1e8b0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1e8c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1e8d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1e8e0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1e8f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1e900 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1e910 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1e920 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1e930 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1e940 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1e950 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1e960 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1e970 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1e980 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1e990 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1e9a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1e9b0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1e9c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e9d0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1e9e0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1e9f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ea00 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1ea10 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1ea20 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1ea30 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1ea40 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ea50 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1ea60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ea70 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1ea80 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1ea90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1eaa0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1eab0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1eac0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1ead0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1eae0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1eaf0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1eb00 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1eb10 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1eb20 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1eb30 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1eb40 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1eb50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1eb60 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1eb70 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1eb80 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1eb90 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1eba0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ebb0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1ebc0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1ebd0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1ebe0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1ebf0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1ec00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1ec10 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1ec20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1ec30 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1ec40 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1ec50 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1ec60 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1ec70 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1ec80 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1ec90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1eca0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ecb0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ecc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1ecd0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1ece0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1ecf0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1ed00 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1ed10 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ed20 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1ed30 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1ed40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1ed50 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1ed60 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1ed70 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1ed80 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1ed90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1eda0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1edb0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1edc0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1edd0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1ede0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1edf0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1ee00 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
1ee10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1ee20 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1ee30 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1ee40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1ee50 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1ee60 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1ee70 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1ee80 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1ee90 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1eea0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1eeb0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1eec0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1eed0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1eee0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1eef0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1ef00 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1ef10 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1ef20 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1ef30 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1ef40 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1ef50 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1ef60 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1ef70 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1ef80 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1ef90 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1efa0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1efb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1efc0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1efd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1efe0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
1eff0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1f000 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1f010 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1f020 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1f030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f040 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1f050 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1f060 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
1f070 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
1f080 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
1f090 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
1f0a0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
1f0b0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1f0c0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
1f0d0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
1f0e0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
1f0f0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
1f100 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
1f110 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
1f120 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
1f130 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1f140 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1f150 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1f160 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
1f170 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
1f180 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1f190 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
1f1a0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
1f1b0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
1f1c0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
1f1d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
1f1e0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
1f1f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
1f200 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
1f210 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
1f220 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
1f230 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
1f240 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
1f250 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
1f260 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
1f270 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
1f280 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
1f290 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
1f2a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1f2b0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
1f2c0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
1f2d0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
1f2e0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1f2f0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1f300 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1f310 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1f320 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1f330 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1f340 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1f350 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1f360 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1f370 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1f380 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1f390 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1f3a0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1f3b0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1f3c0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1f3d0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1f3e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1f3f0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1f400 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1f410 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1f420 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1f430 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1f440 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1f450 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1f460 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1f470 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1f480 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1f490 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1f4a0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1f4b0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1f4c0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1f4d0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1f4e0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1f4f0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1f500 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1f510 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1f520 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1f530 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1f540 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1f550 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1f560 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1f570 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1f580 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1f590 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1f5a0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1f5b0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1f5c0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1f5d0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1f5e0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1f5f0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1f600 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1f610 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1f620 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1f630 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1f640 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1f650 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1f660 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1f670 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1f680 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1f690 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1f6a0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1f6b0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1f6c0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1f6d0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f6e0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1f6f0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1f700 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1f710 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1f720 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1f730 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1f740 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1f750 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1f760 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1f770 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1f780 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1f790 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1f7a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1f7b0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1f7c0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1f7d0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1f7e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1f7f0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1f800 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1f810 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1f820 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1f830 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1f840 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1f850 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1f860 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1f870 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1f880 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f890 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1f8a0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1f8b0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1f8c0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1f8d0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1f8e0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1f8f0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1f900 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1f910 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1f920 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f930 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1f940 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1f950 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1f960 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1f970 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1f980 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
1f990 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
1f9a0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
1f9b0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
1f9c0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
1f9d0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
1f9e0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
1f9f0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
1fa00 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
1fa10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fa20 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
1fa30 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
1fa40 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
1fa50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1fa60 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
1fa70 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
1fa80 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
1fa90 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1faa0 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49  prepare_v2(). ^I
1fab0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
1fac0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
1fad0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
1fae0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1faf0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
1fb00 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
1fb10 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
1fb20 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
1fb30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1fb40 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
1fb50 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
1fb60 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
1fb70 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
1fb80 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
1fb90 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
1fba0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1fbb0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
1fbc0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
1fbd0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
1fbe0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
1fbf0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
1fc00 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
1fc10 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
1fc20 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
1fc30 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
1fc40 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
1fc50 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
1fc60 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1fc70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1fc80 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
1fc90 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1fca0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
1fcb0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
1fcc0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
1fcd0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
1fce0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
1fcf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1fd00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1fd10 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1fd20 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
1fd30 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
1fd40 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1fd50 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
1fd60 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
1fd70 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
1fd80 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
1fd90 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1fda0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
1fdb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1fdc0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
1fdd0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
1fde0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
1fdf0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
1fe00 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
1fe10 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
1fe20 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
1fe30 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
1fe40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1fe50 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
1fe60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
1fe70 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
1fe80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1fe90 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
1fea0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
1feb0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
1fec0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
1fed0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
1fee0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
1fef0 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
1ff00 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
1ff10 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1ff20 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
1ff30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1ff40 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
1ff50 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
1ff60 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1ff70 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
1ff80 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
1ff90 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
1ffa0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
1ffb0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
1ffc0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1ffd0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
1ffe0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
1fff0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
20000 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
20010 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
20020 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
20030 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
20040 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
20050 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
20060 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20070 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
20080 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
20090 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
200a0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
200b0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
200c0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
200d0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
200e0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
200f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
20100 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
20110 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
20120 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
20130 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
20140 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
20150 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
20160 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20170 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
20180 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
20190 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
201a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
201b0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
201c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
201d0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
201e0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
201f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
20200 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20210 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
20220 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
20230 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20240 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
20250 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
20260 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
20270 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
20280 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
20290 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
202a0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
202b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
202c0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
202d0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
202e0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
202f0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
20300 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
20310 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
20320 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
20330 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
20340 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
20350 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
20360 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
20370 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
20380 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
20390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
203a0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
203b0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
203c0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
203d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
203e0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
203f0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
20400 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
20410 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
20420 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
20430 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
20440 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
20450 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
20460 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
20470 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
20480 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
20490 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
204a0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
204b0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
204c0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
204d0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
204e0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
204f0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
20500 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
20510 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
20520 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
20530 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20540 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
20550 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
20560 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
20570 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
20580 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
20590 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
205a0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
205b0 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
205c0 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
205d0 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
205e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
205f0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
20600 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
20610 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
20620 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
20630 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
20640 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
20650 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
20660 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
20670 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20680 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
20690 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
206a0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
206b0 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
206c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
206d0 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
206e0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
206f0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
20700 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
20710 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
20720 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
20730 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
20740 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
20750 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
20760 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
20770 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20780 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
20790 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
207a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
207b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
207c0 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
207d0 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
207e0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
207f0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
20800 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
20810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
20820 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
20830 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
20840 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
20850 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
20860 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
20870 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20880 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
20890 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
208a0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
208b0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
208c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
208d0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
208e0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
208f0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
20900 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
20910 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
20920 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
20930 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
20940 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
20950 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20960 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
20970 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
20980 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
20990 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
209a0 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
209b0 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
209c0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
209d0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
209e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
209f0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
20a00 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
20a10 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
20a20 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
20a30 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
20a40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
20a50 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
20a60 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ctory].*/.SQLITE
20a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
20a80 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
20a90 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20aa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
20ab0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
20ac0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
20ad0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
20ae0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
20af0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
20b00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
20b10 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
20b20 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
20b30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
20b40 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
20b50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
20b60 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
20b70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
20b80 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
20b90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
20ba0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
20bb0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
20bc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
20bd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
20be0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
20bf0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
20c00 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
20c10 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
20c20 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
20c30 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
20c40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
20c50 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
20c60 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
20c70 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
20c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20c90 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
20ca0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
20cb0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
20cc0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
20cd0 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
20ce0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
20cf0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
20d00 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
20d10 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
20d20 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
20d30 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
20d40 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
20d50 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
20d60 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
20d70 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
20d80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
20d90 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
20da0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
20db0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
20dc0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
20dd0 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
20de0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
20df0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
20e00 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
20e10 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
20e20 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
20e30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
20e40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
20e50 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
20e60 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
20e70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
20e80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
20e90 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
20ea0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
20eb0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
20ec0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
20ed0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
20ee0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
20ef0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
20f00 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
20f10 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
20f20 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
20f30 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
20f40 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
20f50 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
20f60 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
20f70 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
20f80 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
20f90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
20fa0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
20fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20fc0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
20fd0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
20fe0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
20ff0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
21000 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
21010 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
21020 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
21030 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
21040 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
21050 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21060 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
21070 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
21080 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
21090 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
210a0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
210b0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
210c0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
210d0 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
210e0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
210f0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
21100 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
21110 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21120 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
21130 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
21140 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
21150 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
21160 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
21170 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
21180 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
21190 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
211a0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
211b0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
211c0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
211d0 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
211e0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
211f0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
21200 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
21210 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
21220 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
21230 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21240 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
21250 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
21260 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
21270 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
21280 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
21290 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
212a0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
212b0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
212c0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
212d0 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
212e0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
212f0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
21300 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
21310 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
21320 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
21330 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
21340 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
21350 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
21360 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
21370 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
21380 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
21390 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
213a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
213b0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
213c0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
213d0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
213e0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
213f0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
21400 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
21410 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
21420 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
21430 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
21440 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
21450 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
21460 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
21470 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
21480 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  able..*/.SQLITE_
21490 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
214a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
214b0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
214c0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
214d0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
214e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
214f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
21500 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
21510 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
21520 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
21530 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54  bDefault);.SQLIT
21540 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
21550 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
21560 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
21570 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
21580 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
21590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
215a0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
215b0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
215c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
215d0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
215e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
215f0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
21600 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
21610 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
21620 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
21630 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
21640 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
21650 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
21660 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
21670 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
21680 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
21690 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
216a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
216b0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
216c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
216d0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
216e0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
216f0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
21700 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
21710 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
21720 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
21730 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
21740 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
21750 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
21760 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
21770 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
21780 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
21790 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
217a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
217b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
217c0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
217d0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
217e0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
217f0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
21800 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
21810 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
21820 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
21830 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
21840 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
21850 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
21860 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
21870 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
21880 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
21890 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
218a0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
218b0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
218c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
218d0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
218e0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
218f0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
21900 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
21910 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
21920 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
21930 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
21940 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
21950 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
21960 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
21970 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
21980 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
21990 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
219a0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
219b0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
219c0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
219d0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
219e0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
219f0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
21a00 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
21a10 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
21a20 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
21a30 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
21a40 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
21a50 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
21a60 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
21a70 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
21a80 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
21a90 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
21aa0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
21ab0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
21ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21ad0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
21ae0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
21af0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
21b00 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
21b10 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
21b20 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
21b30 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
21b40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
21b50 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
21b60 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
21b70 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
21b80 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
21b90 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
21ba0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
21bb0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
21bc0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
21bd0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
21be0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
21bf0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
21c00 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
21c10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21c20 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
21c30 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
21c40 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
21c50 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
21c60 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
21c70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
21c80 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
21c90 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
21ca0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
21cb0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
21cc0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
21cd0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
21ce0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
21cf0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
21d00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
21d10 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
21d20 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
21d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21d40 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
21d50 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
21d60 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
21d70 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
21d80 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
21d90 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
21da0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
21db0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
21dc0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
21dd0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
21de0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
21df0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
21e00 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
21e10 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
21e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
21e30 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
21e40 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
21e50 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
21e60 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
21e70 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
21e80 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
21e90 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
21ea0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
21eb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
21ec0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
21ed0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
21ee0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
21ef0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
21f00 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
21f10 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
21f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
21f30 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
21f40 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
21f50 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
21f60 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21f70 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
21f80 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
21f90 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
21fa0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
21fb0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
21fc0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
21fd0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
21fe0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
21ff0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
22000 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
22010 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22020 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
22030 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
22040 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
22050 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
22060 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
22070 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22080 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22090 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
220a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
220b0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
220c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
220d0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
220e0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
220f0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
22100 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
22110 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
22120 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
22130 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
22140 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
22150 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
22160 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
22170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22180 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
22190 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
221a0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
221b0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
221c0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
221d0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
221e0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
221f0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
22200 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
22210 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
22220 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
22230 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
22240 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
22250 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
22260 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
22270 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
22280 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
22290 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
222a0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
222b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
222c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
222d0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
222e0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
222f0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
22300 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
22310 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
22320 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
22330 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
22340 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
22350 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
22360 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
22370 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
22380 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
22390 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
223a0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
223b0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
223c0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
223d0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
223e0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
223f0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
22400 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
22410 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22420 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
22430 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
22440 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
22450 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
22460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
22470 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
22480 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
22490 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
224a0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
224b0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
224c0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
224d0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
224e0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
224f0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
22500 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
22510 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
22520 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
22530 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
22540 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
22550 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
22560 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
22570 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
22580 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
22590 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
225a0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
225b0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
225c0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
225d0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
225e0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
225f0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
22600 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
22610 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
22620 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
22630 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
22640 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
22650 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
22660 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
22670 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
22680 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
22690 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
226a0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
226b0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
226c0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
226d0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
226e0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
226f0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
22700 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
22710 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
22720 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
22730 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
22740 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
22750 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
22760 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
22770 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22780 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
22790 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
227a0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
227b0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
227c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
227d0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
227e0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
227f0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
22800 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
22810 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
22820 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
22830 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
22840 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
22850 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
22860 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
22870 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
22880 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22890 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
228a0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
228b0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
228c0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
228d0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
228e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
228f0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
22900 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
22910 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
22920 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
22930 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
22940 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
22950 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
22960 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
22970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
22980 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
22990 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
229a0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
229b0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
229c0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
229d0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
229e0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
229f0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
22a00 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
22a10 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
22a20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
22a30 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
22a40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
22a50 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22a60 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
22a70 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
22a80 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
22a90 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
22aa0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22ab0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22ac0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
22ad0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22ae0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
22af0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
22b00 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
22b10 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
22b20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
22b30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
22b40 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
22b50 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
22b60 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
22b70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22b80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
22b90 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
22ba0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
22bb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
22bc0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
22bd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22be0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
22bf0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
22c00 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
22c10 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
22c20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22c30 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
22c40 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
22c50 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
22c60 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
22c70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
22c80 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
22c90 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
22ca0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
22cb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22cc0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
22cd0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
22ce0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
22cf0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
22d00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22d10 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
22d20 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
22d30 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
22d40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
22d60 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
22d70 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
22d80 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
22d90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22da0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
22db0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
22dc0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
22dd0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
22de0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
22df0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
22e00 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
22e10 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
22e20 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
22e30 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
22e40 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
22e50 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
22e60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
22e70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
22e80 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
22e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
22ea0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
22eb0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22ec0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
22ed0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
22ee0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
22ef0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
22f00 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
22f10 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
22f20 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
22f30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22f40 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
22f50 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
22f60 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
22f70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22f80 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
22f90 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
22fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22fb0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
22fc0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
22fd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
22fe0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
22ff0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
23000 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
23010 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
23020 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23030 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
23040 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
23050 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
23060 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
23070 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
23080 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
23090 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
230a0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
230b0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
230c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
230d0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
230e0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
230f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
23100 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
23110 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23120 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
23130 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
23140 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
23150 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
23160 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
23170 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
23180 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
23190 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
231a0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
231b0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
231c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
231d0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
231e0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
231f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
23200 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
23210 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
23220 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23230 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
23240 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
23250 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23260 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
23270 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
23280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23290 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
232a0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
232b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
232c0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
232d0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
232e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
232f0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
23300 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
23310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23320 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
23330 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
23340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23350 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
23360 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
23370 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
23380 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
23390 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
233a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
233b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
233c0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
233d0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
233e0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
233f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
23400 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
23410 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
23420 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
23430 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
23440 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
23450 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
23460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
23480 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
23490 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
234a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
234b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
234c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
234d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
234e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
234f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
23500 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
23510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
23520 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
23530 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
23540 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
23550 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
23560 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
23570 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
23580 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23590 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
235a0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
235b0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
235c0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
235d0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
235e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
235f0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
23600 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
23610 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
23620 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
23630 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
23640 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
23650 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
23660 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
23670 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
23680 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
23690 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
236a0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
236b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
236c0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
236d0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
236e0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
236f0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
23700 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
23710 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
23720 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
23730 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
23740 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
23750 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
23760 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
23770 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
23780 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
23790 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
237a0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
237b0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
237c0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
237d0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
237e0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
237f0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
23800 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
23810 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
23820 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
23830 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
23840 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
23850 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
23860 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
23870 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
23880 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
23890 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
238a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
238b0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
238c0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
238d0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
238e0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
238f0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
23900 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
23910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
23920 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
23930 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
23940 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
23950 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
23960 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
23970 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
23980 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
23990 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
239a0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
239b0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
239c0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
239d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
239e0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
239f0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
23a00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23a10 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
23a20 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
23a30 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
23a40 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
23a50 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
23a60 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
23a70 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
23a80 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
23a90 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
23aa0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
23ab0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
23ac0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
23ad0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
23ae0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
23af0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
23b00 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
23b10 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
23b20 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
23b30 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
23b40 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
23b50 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
23b60 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
23b70 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
23b80 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
23b90 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
23ba0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
23bb0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
23bc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
23bd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23be0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
23bf0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
23c00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23c10 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
23c20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
23c30 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
23c40 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
23c50 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
23c60 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
23c70 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
23c80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
23c90 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
23ca0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
23cb0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
23cc0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
23cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
23ce0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
23cf0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
23d00 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
23d10 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
23d20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
23d30 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
23d40 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
23d50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
23d60 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
23d70 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
23d80 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
23d90 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
23da0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
23db0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
23dc0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
23dd0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
23de0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
23df0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
23e00 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
23e10 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
23e20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
23e30 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
23e40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
23e50 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
23e60 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
23e70 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
23e80 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
23e90 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23ea0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
23eb0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
23ec0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
23ed0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
23ee0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
23ef0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
23f00 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
23f10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23f20 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
23f30 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
23f40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
23f50 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
23f60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
23f70 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
23f80 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
23f90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
23fa0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
23fb0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
23fc0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
23fd0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
23fe0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
23ff0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
24000 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
24010 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
24020 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
24030 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
24040 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
24050 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
24060 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
24070 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
24080 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
24090 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
240a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
240b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
240c0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
240d0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
240e0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
240f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
24100 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
24110 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
24120 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
24130 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
24140 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
24150 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
24160 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
24170 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
24180 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
24190 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
241a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
241b0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
241c0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
241d0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
241e0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
241f0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
24200 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
24210 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
24220 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24230 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
24240 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
24250 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
24260 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
24270 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
24280 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
24290 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
242a0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
242b0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
242c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
242d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
242e0 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
242f0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ol>.*/.SQL
24300 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24310 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
24320 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
24330 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
24340 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
24350 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
24360 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
24370 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
24380 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24390 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
243a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
243b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
243c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
243d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
243e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
243f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
24410 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24420 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24430 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24440 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
24450 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
24470 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
24480 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
24490 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
244a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
244b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
244c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
244d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
244e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
244f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
24500 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24510 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24520 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24530 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24540 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
24550 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
24560 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
24570 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
24580 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
24590 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
245a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
245b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
245c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
245d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
245e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
245f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
24600 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
24610 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
24620 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
24630 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
24640 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
24650 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
24660 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
24670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
24680 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
24690 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
246a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
246b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
246c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
246d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
246e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
246f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24700 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
24710 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
24720 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
24730 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
24740 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
24750 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
24760 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
24770 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
24780 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
24790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
247a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
247b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
247c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
247d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
247e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
247f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
24800 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
24810 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
24820 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
24830 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
24840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24850 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
24860 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
24870 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
24880 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24890 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
248a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
248b0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
248c0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
248d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
248e0 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
248f0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
24900 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
24910 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
24920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24930 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24940 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
24950 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
24960 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
24970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
24980 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
24990 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
249a0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
249b0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
249c0 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
249d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
249e0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
249f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24a00 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
24a10 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
24a20 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
24a30 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
24a40 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
24a50 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
24a60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
24a70 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
24a80 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
24a90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
24aa0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
24ab0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
24ac0 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
24ad0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
24ae0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
24af0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
24b00 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
24b10 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
24b20 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
24b30 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
24b40 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
24b50 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
24b60 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
24b70 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
24b80 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
24b90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
24ba0 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
24bb0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
24bc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
24bd0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
24be0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
24bf0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
24c00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
24c10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
24c20 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
24c30 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
24c40 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
24c50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24c60 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
24c70 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
24c80 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
24c90 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
24ca0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
24cb0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
24cc0 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
24cd0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
24ce0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
24cf0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
24d00 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
24d10 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
24d20 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
24d30 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
24d40 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
24d50 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
24d60 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
24d70 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
24d80 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
24d90 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
24da0 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
24db0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
24dc0 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
24dd0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
24de0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
24df0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
24e00 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
24e10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
24e20 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
24e30 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
24e40 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
24e50 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
24e60 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
24e70 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
24e80 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
24e90 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
24ea0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
24eb0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24ec0 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
24ed0 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
24ee0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
24ef0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
24f00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24f20 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
24f30 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
24f40 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
24f50 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
24f60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
24f70 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
24f80 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24f90 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
24fa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24fb0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
24fc0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
24fd0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
24fe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
24ff0 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
25000 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
25010 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
25020 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
25030 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
25040 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
25050 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
25060 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
25070 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
25080 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
25090 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
250a0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
250b0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
250c0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
250d0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
250e0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
250f0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
25100 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
25110 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
25120 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
25130 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
25140 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
25150 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
25160 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
25170 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
25180 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
25190 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
251a0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
251b0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
251c0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
251d0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
251e0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
251f0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
25200 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
25210 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
25220 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
25230 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
25240 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
25250 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
25260 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
25270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
25280 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
25290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
252a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
252b0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
252c0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
252d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
252e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
252f0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
25300 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25310 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
25320 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
25330 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
25340 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
25350 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
25360 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
25370 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
25380 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
25390 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
253a0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
253b0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
253c0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
253d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
253e0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
253f0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
25400 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
25410 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
25420 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
25430 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25440 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
25450 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
25460 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
25470 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
25480 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
25490 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
254a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
254b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
254c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
254d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
254e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
254f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
25500 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
25510 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
25520 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
25530 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
25540 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
25550 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
25560 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25570 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
25580 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
25590 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
255a0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
255b0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
255c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
255d0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
255e0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
255f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
25600 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25610 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
25620 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
25630 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
25640 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25650 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
25660 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
25670 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
25680 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
25690 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
256a0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
256b0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
256c0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
256d0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
256e0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
256f0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
25700 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
25710 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
25720 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
25730 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
25740 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
25750 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
25760 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
25770 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
25780 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25790 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
257a0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
257b0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
257c0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
257d0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
257e0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
257f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
25800 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
25810 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
25820 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
25830 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
25840 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
25850 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
25860 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
25870 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
25880 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
25890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
258a0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
258b0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
258c0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
258d0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
258e0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
258f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25900 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
25910 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
25920 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
25930 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
25940 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
25950 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
25960 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
25970 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
25980 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25990 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
259a0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
259b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
259c0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
259d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
259e0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
259f0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
25a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
25a10 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
25a20 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
25a30 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
25a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25a50 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
25a60 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
25a70 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
25a80 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
25a90 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
25aa0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
25ab0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
25ac0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
25ad0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
25ae0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
25af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
25b00 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
25b10 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
25b20 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
25b30 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
25b40 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
25b50 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25b60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25b70 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
25b80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25b90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
25ba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
25bb0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
25bc0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
25bd0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
25be0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
25bf0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
25c00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
25c10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
25c20 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
25c30 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
25c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
25c50 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
25c60 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
25c70 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
25c80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
25c90 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
25ca0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
25cb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
25cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
25cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25ce0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
25cf0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
25d00 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
25d10 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
25d20 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
25d30 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
25d40 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
25d50 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
25d60 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
25d70 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
25d80 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
25d90 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
25da0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
25db0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
25dc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25dd0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
25de0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
25df0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
25e00 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
25e10 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
25e20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
25e30 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
25e40 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
25e50 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
25e60 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
25e70 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
25e80 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
25e90 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
25ea0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
25eb0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
25ec0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
25ed0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
25ee0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
25ef0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
25f00 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
25f10 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
25f20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
25f30 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
25f40 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
25f50 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
25f60 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
25f70 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
25f80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
25f90 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
25fa0 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
25fb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
25fc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
25fd0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
25fe0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
25ff0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
26000 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
26010 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
26020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26030 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
26040 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
26050 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
26060 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
26070 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
26080 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
26090 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
260a0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
260b0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
260c0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
260d0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
260e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
260f0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
26100 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
26110 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
26120 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
26130 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
26140 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
26150 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
26160 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
26170 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
26180 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
26190 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
261a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
261b0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
261c0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
261d0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
261e0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
261f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
26200 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
26210 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
26220 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
26230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
26240 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
26250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26260 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
26270 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
26280 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
26290 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
262a0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
262b0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
262c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
262d0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
262e0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
262f0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
26300 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
26310 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26320 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
26330 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
26340 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
26350 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
26360 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
26370 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
26380 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
26390 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
263a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
263b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
263c0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
263d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
263e0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
263f0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
26400 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
26410 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
26420 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
26430 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
26440 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
26450 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
26460 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26470 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
26480 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
26490 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
264a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
264b0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
264c0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
264d0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
264e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
264f0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
26500 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
26510 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61  6() then that pa
26520 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
26530 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
26540 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
26550 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
26560 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
26570 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
26580 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
26590 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
265a0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
265b0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
265c0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
265d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
265e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
265f0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
26600 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
26610 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
26620 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
26630 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
26640 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
26650 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
26660 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
26670 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
26680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
26690 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
266a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
266b0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
266c0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
266d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
266e0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
266f0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
26700 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
26710 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
26720 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
26730 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
26740 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
26750 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
26760 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
26770 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
26780 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
26790 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
267a0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
267b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
267c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
267d0 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
267e0 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
267f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
26800 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
26810 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
26820 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
26830 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
26840 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
26850 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
26860 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
26870 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
26880 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
26890 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
268a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
268b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
268c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
268d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
268e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
268f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
26900 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
26910 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
26920 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
26930 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
26940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26950 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
26960 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
26970 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
26980 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
26990 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
269a0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
269b0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
269c0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
269d0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
269e0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
269f0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
26a00 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
26a10 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
26a20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
26a30 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
26a40 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
26a50 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
26a60 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
26a70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
26a80 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
26a90 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
26aa0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
26ab0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
26ac0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
26ad0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
26ae0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
26af0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
26b00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
26b10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
26b20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
26b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
26b40 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
26b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
26b60 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
26b70 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
26b80 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
26b90 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
26ba0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
26bb0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
26bc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
26bd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
26be0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
26bf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
26c00 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
26c10 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
26c20 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
26c30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26c40 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
26c50 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
26c60 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
26c70 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
26c80 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
26c90 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
26ca0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
26cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
26cc0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
26cd0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
26ce0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
26cf0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
26d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26d10 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
26d20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
26d30 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
26d40 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
26d50 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
26d60 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
26d70 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
26d80 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
26d90 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
26da0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
26db0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
26dc0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
26dd0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
26de0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
26df0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
26e10 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
26e20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26e30 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
26e40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26e50 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26e60 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
26e70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26e80 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
26e90 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26ea0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
26eb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26ec0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
26ee0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
26ef0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
26f00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
26f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26f30 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
26f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26f50 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
26f60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26f70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
26f80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26f90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
26fa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26fb0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
26fc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26fd0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
26fe0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26ff0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
27000 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
27010 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27030 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27040 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
27050 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
27060 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
27070 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27080 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
27090 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
270a0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
270b0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
270c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
270d0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
270e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
270f0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
27100 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27110 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
27120 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
27130 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
27140 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
27150 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
27160 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
27170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27180 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
27190 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
271a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
271b0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
271c0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
271d0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
271e0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
271f0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
27200 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
27210 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
27220 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
27230 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
27240 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
27250 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
27260 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
27270 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27280 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
27290 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
272a0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
272b0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
272c0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
272d0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
272e0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
272f0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
27300 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
27310 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
27320 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
27330 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
27340 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
27350 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27360 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
27370 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
27380 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27390 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
273a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
273b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
273c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
273d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
273e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
273f0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
27400 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27410 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
27420 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
27430 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
27440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27450 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
27460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27470 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
27480 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
27490 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
274a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
274b0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
274c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
274d0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
274e0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
274f0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
27500 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
27510 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
27520 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
27530 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
27540 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
27550 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
27560 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
27570 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
27580 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
27590 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
275a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
275b0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
275c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
275d0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
275e0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
275f0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
27600 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
27610 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
27620 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
27630 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
27640 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
27650 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
27660 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
27670 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
27680 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
27690 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
276a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
276b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
276c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
276d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
276e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
276f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
27700 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
27710 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
27720 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
27730 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
27740 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
27750 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
27760 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
27770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
27780 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
27790 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
277a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
277b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
277c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
277d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
277e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
277f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27800 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
27810 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27830 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27840 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27850 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
27860 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
27870 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
27880 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
27890 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
278a0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
278b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
278c0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
278d0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
278e0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
278f0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
27900 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
27910 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
27920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27930 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27940 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
27950 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27960 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27970 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
27980 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27990 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
279a0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
279b0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
279c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
279d0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
279e0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
279f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27a00 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27a10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27a20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27a30 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27a40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27a50 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27a60 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27a70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27a80 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27a90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27aa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27ab0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
27ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
27ad0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
27ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27af0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
27b00 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
27b10 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
27b20 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
27b30 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
27b40 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
27b50 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
27b60 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
27b70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27b80 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
27b90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27ba0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
27bb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
27bc0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
27bd0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
27be0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
27bf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
27c00 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
27c10 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
27c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
27c30 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
27c40 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
27c50 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
27c60 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
27c70 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
27c80 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
27c90 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
27cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
27cc0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
27cd0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
27ce0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
27cf0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
27d00 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
27d10 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
27d20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27d30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
27d40 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
27d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27d60 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
27d70 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27d90 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
27da0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
27db0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
27dc0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
27dd0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
27de0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
27df0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
27e00 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
27e10 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
27e20 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
27e30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
27e40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27e50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
27e60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27e70 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
27e80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
27e90 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
27ea0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
27eb0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
27ec0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
27ed0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
27ee0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
27ef0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27f00 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
27f10 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
27f20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27f30 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
27f40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
27f50 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
27f60 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
27f70 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
27f80 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
27f90 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
27fa0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
27fb0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
27fc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27fd0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
27fe0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
27ff0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
28000 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
28010 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
28020 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
28030 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
28040 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
28050 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
28060 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
28070 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
28080 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
28090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
280a0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
280b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
280c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
280d0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
280e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
280f0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
28100 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
28110 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
28120 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
28130 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
28140 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
28150 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
28160 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
28170 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
28180 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
28190 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
281a0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
281b0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
281c0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
281d0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
281e0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
281f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
28200 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
28210 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
28220 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
28230 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
28240 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
28250 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
28260 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
28270 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28290 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
282a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
282b0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
282c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
282d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
282e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
282f0 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
28300 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
28310 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
28320 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
28330 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
28340 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
28350 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
28360 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
28370 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
28380 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
28390 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
283a0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
283b0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
283c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
283d0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
283e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
283f0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
28400 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
28410 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
28420 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
28430 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
28440 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
28450 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
28460 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
28470 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
28480 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
28490 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
284a0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
284b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
284c0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
284d0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
284e0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
284f0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
28500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
28510 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
28520 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
28530 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
28540 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
28550 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
28560 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
28570 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
28580 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
28590 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
285a0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
285b0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
285c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
285d0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
285e0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
285f0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
28600 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
28610 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
28620 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
28630 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
28640 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
28650 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
28660 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
28670 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
28680 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
28690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
286a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
286b0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
286c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
286d0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
286e0 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
286f0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
28700 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
28710 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
28720 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
28730 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
28740 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
28750 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
28760 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
28770 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
28780 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
28790 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
287a0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
287b0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
287c0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
287d0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
287e0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
287f0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
28800 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
28810 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
28820 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
28830 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
28840 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
28850 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
28860 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
28870 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
28880 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
28890 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
288a0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
288b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
288c0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
288d0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
288e0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
288f0 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
28900 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
28910 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
28920 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
28930 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
28940 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
28950 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
28960 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
28970 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
28980 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
28990 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
289a0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
289b0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
289c0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
289d0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
289e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
289f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
28a00 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
28a10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
28a20 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
28a30 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
28a40 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
28a50 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
28a60 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
28a70 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
28a80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
28a90 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
28aa0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
28ab0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
28ac0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28ad0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
28ae0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
28af0 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
28b00 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
28b10 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
28b20 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
28b30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
28b40 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28b50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28b60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28b70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28b80 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28b90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28ba0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
28bb0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
28bc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28bd0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
28be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28bf0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
28c00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28c10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
28c20 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
28c30 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
28c40 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
28c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28c60 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
28c70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28c80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28c90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28ca0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
28cb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28cc0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
28cd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
28ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
28cf0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
28d00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28d20 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
28d30 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
28d40 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
28d50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28d60 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
28d70 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
28d80 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
28d90 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
28da0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
28db0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
28dc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
28dd0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
28de0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
28df0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
28e00 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
28e10 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
28e20 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
28e30 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
28e40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
28e50 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
28e60 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28e80 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
28e90 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
28ea0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
28eb0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
28ec0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
28ed0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
28ee0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
28ef0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
28f00 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
28f10 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
28f20 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
28f30 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
28f40 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
28f50 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
28f60 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
28f70 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
28f80 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
28f90 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
28fa0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
28fb0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
28fc0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
28fd0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
28fe0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
28ff0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
29000 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
29010 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
29020 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
29030 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
29040 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
29050 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
29060 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
29070 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
29080 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
29090 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
290a0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
290b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
290c0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
290d0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
290e0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
290f0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
29100 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
29110 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
29120 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
29130 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
29140 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
29150 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
29160 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
29170 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
29180 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
29190 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
291a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
291b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
291c0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
291d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
291e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
291f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29200 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
29210 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29220 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
29230 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
29240 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29250 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
29260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29270 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
29280 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
29290 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
292a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
292b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
292c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
292d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
292e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
292f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29310 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
29320 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
29330 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
29340 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
29350 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
29360 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
29370 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
29380 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
29390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
293a0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
293b0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
293c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
293d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
293e0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
293f0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
29400 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29410 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
29420 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
29430 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
29440 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
29450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29460 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29470 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
29480 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
29490 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
294a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
294b0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
294c0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
294d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
294e0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
294f0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
29500 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
29510 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
29520 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
29530 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
29540 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
29550 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
29560 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
29570 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
29580 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
29590 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
295a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
295b0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
295c0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
295d0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
295e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
295f0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
29600 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
29610 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
29620 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29630 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
29640 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
29650 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
29660 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
29670 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
29680 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
29690 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
296a0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
296b0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
296c0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
296d0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
296e0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
296f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
29700 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29710 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
29720 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
29730 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
29740 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
29750 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
29760 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
29770 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
29780 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
29790 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
297a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
297b0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
297c0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
297d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
297e0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
297f0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
29800 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
29810 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
29820 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
29830 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
29840 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29850 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
29860 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
29870 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
29880 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
29890 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
298a0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
298b0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
298c0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
298d0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
298e0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
298f0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
29900 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
29910 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
29920 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
29930 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
29940 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
29950 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
29960 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
29970 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
29980 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
29990 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
299a0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
299b0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
299c0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
299d0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
299e0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
299f0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
29a00 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
29a10 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
29a20 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
29a30 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29a40 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
29a50 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
29a60 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
29a70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29a80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
29a90 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
29aa0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
29ab0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
29ac0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
29ad0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
29ae0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
29af0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
29b00 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
29b10 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
29b20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
29b30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29b40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
29b50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
29b60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
29b70 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
29b80 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
29b90 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29ba0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
29bb0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
29bc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
29bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
29be0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
29bf0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
29c00 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
29c10 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
29c20 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
29c30 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
29c40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
29c50 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
29c60 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
29c70 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
29c80 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
29c90 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
29ca0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
29cb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
29cc0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
29cd0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
29ce0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
29cf0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
29d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29d10 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
29d20 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
29d30 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
29d40 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
29d50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
29d60 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
29d70 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
29d80 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
29d90 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
29da0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29db0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
29dc0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
29dd0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
29de0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
29df0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
29e00 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
29e10 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
29e20 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
29e30 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
29e40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
29e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29e60 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
29e70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
29e80 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
29e90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
29ea0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
29eb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
29ec0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
29ed0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
29ee0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
29ef0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
29f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
29f10 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
29f20 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
29f30 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
29f40 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
29f50 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
29f60 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
29f70 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
29f80 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
29f90 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
29fa0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
29fb0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
29fc0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
29fd0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
29fe0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
29ff0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2a000 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2a010 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2a020 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2a030 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2a040 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2a050 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2a060 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2a070 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2a080 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2a090 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2a0a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2a0b0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2a0c0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2a0d0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2a0e0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2a0f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2a100 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2a110 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2a120 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2a130 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a140 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2a150 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2a160 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2a170 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2a180 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2a190 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2a1a0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2a1b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2a1c0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2a1d0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2a1e0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2a1f0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2a200 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2a210 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2a220 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2a230 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2a240 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2a250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a260 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2a270 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2a280 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2a290 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2a2a0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2a2b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a2c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2a2d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2a2e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2a2f0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2a300 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2a310 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2a320 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2a330 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a340 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2a350 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2a360 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
2a370 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2a380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a390 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2a3a0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2a3b0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2a3c0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a3d0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2a3e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2a3f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2a400 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2a410 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2a420 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2a430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2a440 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2a450 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2a460 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2a470 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2a480 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2a490 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2a4a0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2a4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2a4c0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2a4d0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2a4e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2a4f0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2a500 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2a510 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2a520 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2a530 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2a540 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2a550 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a560 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2a570 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2a580 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2a590 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2a5a0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2a5b0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2a5c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2a5d0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2a5e0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2a5f0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2a600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a610 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2a620 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2a630 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2a640 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2a650 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2a660 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2a670 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2a680 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2a690 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2a6a0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2a6b0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2a6c0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2a6d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2a6e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a6f0 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2a700 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a710 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2a720 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2a730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a740 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2a750 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2a760 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2a770 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2a780 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2a790 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2a7a0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2a7b0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2a7c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2a7d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2a7e0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2a7f0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2a800 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2a810 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2a820 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2a830 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2a840 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2a850 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2a860 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2a870 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2a880 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2a890 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2a8a0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2a8b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a8c0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2a8d0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2a8e0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2a8f0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2a900 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2a910 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2a920 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2a930 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2a940 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2a950 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2a960 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a970 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2a980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2a990 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2a9a0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2a9b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2a9c0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2a9d0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2a9e0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2a9f0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2aa00 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2aa10 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2aa20 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2aa30 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2aa40 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2aa50 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2aa60 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2aa70 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2aa80 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2aa90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2aaa0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2aab0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2aac0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2aad0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2aae0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2aaf0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2ab00 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2ab10 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2ab20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2ab30 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2ab40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2ab50 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2ab60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ab70 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2ab80 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2ab90 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2aba0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2abb0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2abc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2abd0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2abe0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2abf0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2ac00 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2ac10 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2ac20 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2ac30 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2ac40 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2ac50 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2ac60 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2ac70 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2ac80 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2ac90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2aca0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2acb0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2acc0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2acd0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2ace0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2acf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2ad00 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2ad10 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2ad20 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2ad30 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2ad40 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2ad50 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2ad60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2ad70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2ad80 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2ad90 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2ada0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2adb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2adc0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2add0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2ade0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2adf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2ae00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ae10 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2ae20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2ae30 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2ae40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ae50 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2ae60 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2ae70 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2ae80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ae90 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2aea0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2aeb0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2aec0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2aed0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2aee0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2aef0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2af00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2af10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2af20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2af30 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2af40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2af50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2af60 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2af70 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2af80 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2af90 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2afa0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2afb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2afc0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2afd0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2afe0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2aff0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2b000 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2b010 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2b020 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2b030 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2b040 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2b050 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b060 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2b070 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2b080 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2b090 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2b0a0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2b0b0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2b0c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2b0d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2b0e0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2b0f0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2b100 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2b110 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2b120 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2b130 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2b140 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2b150 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2b160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2b170 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2b180 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2b190 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2b1a0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2b1b0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2b1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2b1d0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2b1e0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2b1f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b200 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2b210 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2b220 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2b230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b240 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2b250 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2b260 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2b270 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2b280 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b290 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2b2a0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2b2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2b2c0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2b2d0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2b2e0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2b2f0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2b300 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2b310 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2b320 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2b330 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2b340 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2b350 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2b360 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2b370 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2b380 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2b390 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2b3a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b3b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2b3c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2b3d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2b3e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b3f0 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2b400 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2b410 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2b420 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2b430 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2b440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b450 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2b460 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2b470 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2b480 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2b490 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2b4a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2b4b0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2b4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b4d0 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2b4e0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2b4f0 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2b500 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2b510 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2b520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2b530 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2b540 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2b550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b560 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2b570 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b580 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2b590 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2b5a0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2b5b0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2b5c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2b5d0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2b5e0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2b5f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2b600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b610 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2b620 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2b630 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2b640 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2b650 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2b660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2b670 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2b680 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2b690 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2b6a0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2b6b0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2b6c0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2b6d0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2b6e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2b6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2b700 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2b710 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2b720 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2b730 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2b740 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2b750 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2b760 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2b770 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2b780 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2b790 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2b7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b7b0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2b7c0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2b7d0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2b7e0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2b7f0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2b800 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2b810 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2b820 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2b830 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2b840 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2b850 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2b860 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2b870 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2b880 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2b890 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b8a0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2b8b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b8c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2b8d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2b8e0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2b8f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2b900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2b910 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2b920 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2b930 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2b940 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2b950 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2b960 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2b970 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2b980 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2b990 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2b9a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2b9b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2b9c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2b9d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2b9e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2b9f0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2ba00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2ba10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2ba20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2ba30 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2ba40 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2ba50 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2ba60 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2ba70 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2ba80 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2ba90 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2baa0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2bab0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2bac0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2bad0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2bae0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2baf0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2bb00 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2bb10 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2bb20 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2bb30 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2bb40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2bb50 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2bb60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2bb70 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2bb80 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2bb90 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2bba0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2bbb0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2bbc0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2bbd0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2bbe0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2bbf0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2bc00 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2bc10 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2bc20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2bc30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2bc40 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2bc50 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2bc60 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2bc70 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2bc80 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2bc90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2bca0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2bcb0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2bcc0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2bcd0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2bce0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2bcf0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2bd00 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2bd10 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2bd20 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2bd30 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2bd40 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2bd50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2bd60 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2bd70 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2bd80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2bd90 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2bda0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2bdb0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2bdc0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2bdd0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2bde0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2bdf0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2be00 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2be10 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2be20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2be30 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2be40 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2be50 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2be60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2be70 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2be80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2be90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2bea0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2beb0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2bec0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2bed0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2bee0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2bef0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2bf00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2bf10 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2bf20 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2bf30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2bf40 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2bf50 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2bf60 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2bf70 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2bf80 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2bf90 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2bfa0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2bfb0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2bfc0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2bfd0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2bfe0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2bff0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2c000 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2c010 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2c020 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2c030 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2c040 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2c050 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2c060 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2c070 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2c080 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2c090 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2c0a0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2c0b0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2c0c0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2c0d0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2c0e0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2c0f0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2c100 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2c110 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2c120 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2c130 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2c140 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2c150 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2c160 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c170 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2c180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c190 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2c1a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c1b0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2c1c0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2c1d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2c1e0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2c1f0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2c200 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2c210 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2c220 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2c230 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2c240 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2c250 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2c260 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2c270 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2c280 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2c290 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2c2a0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2c2b0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2c2c0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2c2d0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2c2e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2c2f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2c300 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2c310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c320 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2c330 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2c340 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2c350 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2c360 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2c370 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2c380 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2c390 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2c3a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2c3b0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2c3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c3d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2c3e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c3f0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2c400 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2c410 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2c420 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2c430 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2c440 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2c450 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2c460 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2c470 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2c480 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2c490 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2c4a0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2c4b0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2c4c0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2c4d0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2c4e0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2c4f0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2c500 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2c510 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2c520 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2c530 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2c540 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2c550 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2c560 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2c570 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2c580 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2c590 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2c5a0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2c5b0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2c5c0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2c5d0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2c5e0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2c5f0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2c600 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2c610 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2c620 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2c630 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2c640 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2c650 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2c660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c670 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2c680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c690 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2c6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c6b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2c6c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2c6d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2c6e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c700 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2c710 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2c720 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2c730 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2c740 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2c750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c760 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2c770 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c780 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2c790 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2c7a0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2c7b0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2c7c0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2c7d0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2c7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c7f0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2c800 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2c810 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2c820 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2c830 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2c840 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2c850 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2c860 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2c870 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c880 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2c890 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2c8a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2c8b0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2c8c0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2c8d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c8e0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2c8f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c900 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2c910 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2c920 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2c930 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2c940 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2c950 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2c960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c970 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2c980 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2c990 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2c9a0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2c9b0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2c9c0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2c9d0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2c9e0 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2c9f0 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2ca00 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2ca10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ca20 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2ca30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ca40 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2ca50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2ca70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2ca80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2ca90 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2caa0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2cab0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2cac0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2cad0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2cae0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2caf0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2cb00 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2cb10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2cb20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2cb30 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2cb40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2cb50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2cb60 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2cb70 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2cb80 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
2cb90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2cba0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cbb0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2cbc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cbd0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2cbe0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2cbf0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(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 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2cc40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2cc50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2cc60 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2cc70 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2cc80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cc90 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2cca0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2ccb0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2ccc0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ccd0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2cce0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2ccf0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2cd00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2cd10 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2cd20 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
2cd30 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2cd40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2cd50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2cd60 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2cd70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2cd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cd90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2cda0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2cdb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2cdc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cdd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2cde0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2cdf0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
2ce00 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2ce10 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2ce20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ce30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce40 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2ce50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2ce60 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2ce70 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2ce80 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2ce90 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2cea0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2ceb0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2cec0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ced0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2cee0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2cef0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2cf00 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2cf10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2cf20 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2cf30 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2cf40 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2cf50 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2cf60 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2cf70 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2cf80 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2cf90 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2cfa0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2cfb0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2cfc0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2cfd0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2cfe0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2cff0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2d000 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2d010 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2d020 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2d030 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2d040 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2d050 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2d060 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2d070 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2d080 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2d090 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2d0a0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2d0b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2d0c0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2d0d0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2d0e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d0f0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2d100 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2d110 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2d120 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2d130 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2d140 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2d150 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2d160 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2d170 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2d180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2d190 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2d1a0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2d1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d1c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2d1d0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2d1e0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2d1f0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2d200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d210 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2d220 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2d230 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2d240 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2d250 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2d260 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2d270 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2d280 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2d290 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2d2a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2d2b0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2d2c0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2d2d0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2d2e0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2d2f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2d300 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2d310 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2d320 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d330 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2d340 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2d350 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2d360 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d370 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2d380 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2d390 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d3a0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d3b0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2d3c0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2d3d0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2d3e0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2d3f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2d400 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2d410 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2d420 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2d430 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2d440 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2d450 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2d460 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2d470 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2d480 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2d490 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2d4a0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2d4b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2d4c0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2d4d0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2d4e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d4f0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2d500 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2d510 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2d520 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2d530 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2d540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2d550 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2d560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d570 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2d580 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2d590 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2d5a0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2d5b0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2d5c0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2d5d0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2d5e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d5f0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2d600 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2d610 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2d620 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2d630 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2d640 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2d660 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2d670 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2d680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2d690 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2d6a0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2d6b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2d6c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2d6d0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2d6e0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2d6f0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2d700 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d710 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2d720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d730 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
2d740 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d750 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2d760 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d780 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2d790 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2d7a0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2d7b0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2d7c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2d7d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d7e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d7f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2d800 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d810 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d820 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2d830 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2d840 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2d850 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2d860 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2d870 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2d880 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2d890 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2d8a0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2d8b0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2d8c0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2d8d0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2d8e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2d8f0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2d900 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2d910 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2d920 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2d930 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2d940 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2d950 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2d960 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2d970 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2d980 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2d990 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2d9a0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2d9b0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2d9c0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2d9d0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2d9e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2d9f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2da00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2da10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2da20 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2da30 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2da40 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2da50 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2da60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2da70 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2da80 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2da90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2daa0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2dab0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2dac0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2dad0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2dae0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2daf0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2db00 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2db10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2db20 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2db30 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2db40 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2db50 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2db60 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2db70 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2db80 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2db90 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2dba0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2dbb0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2dbc0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2dbd0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2dbe0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2dbf0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2dc00 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2dc10 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2dc20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2dc30 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2dc40 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2dc50 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2dc60 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2dc70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2dc80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2dc90 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2dca0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2dcb0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2dcc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2dcd0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2dce0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2dcf0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2dd00 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2dd10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2dd20 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2dd30 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2dd40 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2dd50 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2dd60 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2dd70 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2dd80 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2dd90 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2dda0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2ddb0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2ddc0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2ddd0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2dde0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2ddf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2de00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2de10 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2de20 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2de30 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2de40 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2de50 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2de60 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2de70 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2de80 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2de90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2dea0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2deb0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2dec0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2ded0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2dee0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2def0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2df00 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2df10 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2df20 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2df30 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2df40 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2df50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2df60 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2df70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2df80 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2df90 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2dfa0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2dfb0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2dfc0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2dfd0 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2dfe0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2dff0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2e000 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2e010 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2e020 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2e030 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2e040 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2e050 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2e060 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2e070 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2e080 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2e090 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2e0a0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2e0b0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2e0c0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2e0d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2e0e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2e0f0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2e100 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2e110 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2e120 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2e130 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2e140 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2e150 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2e160 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2e170 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2e180 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2e190 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2e1a0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2e1b0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2e1c0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2e1d0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2e1e0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2e1f0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2e200 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2e210 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2e220 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2e230 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2e240 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2e250 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e270 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2e280 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2e290 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2e2a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2e2b0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2e2c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2e2d0 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2e2e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2e2f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2e300 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2e310 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2e320 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2e330 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2e340 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2e350 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2e360 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2e370 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2e380 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2e390 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2e3a0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2e3b0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2e3c0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2e3d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2e3e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2e3f0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2e400 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2e410 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2e420 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2e430 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2e440 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2e450 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2e460 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2e470 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2e480 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2e490 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2e4a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e4b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2e4c0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2e4d0 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2e4e0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2e4f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2e500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2e510 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2e520 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2e530 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2e540 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2e550 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2e560 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2e570 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2e580 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2e590 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2e5a0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2e5b0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2e5c0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2e5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2e5e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2e5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2e600 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2e610 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2e620 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e630 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2e640 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2e650 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2e660 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2e670 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2e680 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2e690 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2e6a0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e6b0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2e6c0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2e6d0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2e6e0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2e6f0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2e700 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2e710 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2e720 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2e730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e740 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2e750 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2e760 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2e770 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2e780 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e790 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2e7a0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2e7b0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2e7c0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2e7d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2e7e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2e7f0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2e800 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2e810 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2e820 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2e830 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2e840 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2e850 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e860 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2e870 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2e880 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2e890 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2e8a0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2e8b0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e8c0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e8d0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2e8e0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2e8f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2e900 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2e910 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2e920 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2e930 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e940 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2e950 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e960 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2e970 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2e980 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2e990 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2e9a0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2e9b0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2e9c0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2e9d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2e9e0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2e9f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2ea00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2ea10 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2ea20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2ea30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ea40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ea50 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2ea60 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2ea70 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2ea80 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2ea90 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2eaa0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2eab0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2eac0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ead0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2eae0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2eaf0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2eb00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2eb10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2eb20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2eb30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2eb40 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2eb50 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2eb60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2eb70 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2eb80 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2eb90 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2eba0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2ebb0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2ebc0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2ebd0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2ebe0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2ebf0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2ec00 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2ec10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2ec20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2ec30 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2ec40 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2ec50 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
2ec60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2ec70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ec80 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2ec90 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2eca0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2ecb0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2ecc0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2ecd0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2ece0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2ecf0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2ed00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2ed10 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2ed20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ed30 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2ed40 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2ed50 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2ed60 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2ed70 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2ed80 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2ed90 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2eda0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2edb0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2edc0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2edd0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2ede0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2edf0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2ee00 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2ee10 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2ee20 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2ee30 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2ee40 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2ee50 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2ee60 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2ee70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2ee80 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2ee90 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2eea0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2eeb0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2eec0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2eed0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2eee0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eef0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2ef00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2ef10 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2ef20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ef30 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2ef40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2ef50 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2ef60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2ef70 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2ef80 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2ef90 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2efa0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2efb0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2efc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2efd0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2efe0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2eff0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2f000 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2f010 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2f020 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2f030 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2f040 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2f050 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2f060 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2f070 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2f080 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f090 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2f0a0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2f0b0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
2f0c0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
2f0d0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
2f0e0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
2f0f0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2f100 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f110 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
2f120 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
2f130 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2f140 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f150 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2f160 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2f170 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2f180 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2f190 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2f1a0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2f1b0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2f1c0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
2f1d0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2f1e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
2f1f0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2f200 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
2f210 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f220 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
2f230 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2f240 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
2f250 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2f260 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
2f270 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
2f280 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2f290 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
2f2a0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2f2b0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
2f2c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2f2d0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2f2e0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2f2f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
2f300 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
2f310 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
2f320 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2f330 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
2f340 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
2f350 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
2f360 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
2f370 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
2f380 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
2f390 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
2f3a0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
2f3b0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
2f3c0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
2f3d0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
2f3e0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
2f3f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f400 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2f410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f420 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2f430 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
2f440 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2f450 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f460 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2f470 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
2f480 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
2f490 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
2f4a0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2f4b0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
2f4c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f4d0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
2f4e0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
2f4f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2f500 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
2f510 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
2f520 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
2f530 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2f540 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
2f550 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
2f560 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f570 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
2f580 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f590 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
2f5a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f5b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2f5c0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
2f5d0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
2f5e0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
2f5f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f600 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
2f610 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
2f620 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
2f630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2f640 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2f650 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2f660 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2f670 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2f680 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2f690 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2f6a0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2f6b0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2f6c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f6d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2f6e0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2f6f0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2f700 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2f710 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2f720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f730 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2f740 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2f750 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
2f760 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2f770 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2f780 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2f790 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
2f7a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f7b0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2f7c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f7d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2f7e0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2f7f0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2f800 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2f810 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2f820 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
2f830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2f840 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
2f850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2f860 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
2f870 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
2f880 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
2f890 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
2f8a0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
2f8b0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
2f8c0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
2f8d0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
2f8e0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
2f8f0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
2f900 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
2f910 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
2f920 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
2f930 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
2f940 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
2f950 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
2f960 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
2f970 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
2f980 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
2f990 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
2f9a0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
2f9b0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
2f9c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2f9d0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2f9e0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2f9f0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
2fa00 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
2fa10 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
2fa20 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
2fa30 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
2fa40 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2fa50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2fa60 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2fa70 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
2fa80 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
2fa90 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
2faa0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
2fab0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
2fac0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2fad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2fae0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
2faf0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
2fb00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fb10 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2fb20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2fb30 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
2fb40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2fb50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2fb60 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2fb70 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2fb80 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2fb90 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2fba0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2fbb0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54  meters..*/.SQLIT
2fbc0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fbd0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2fbe0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
2fbf0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2fc00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
2fc10 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
2fc20 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fc30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2fc40 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
2fc50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2fc60 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
2fc70 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2fc80 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2fc90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2fca0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2fcb0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
2fcc0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fcd0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
2fce0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2fcf0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2fd00 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2fd10 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
2fd20 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2fd30 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2fd40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2fd50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2fd60 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2fd70 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2fd80 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2fd90 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2fda0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2fdb0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2fdc0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2fdd0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2fde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fdf0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2fe00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2fe10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
2fe20 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
2fe30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fe40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2fe50 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2fe60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2fe70 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2fe80 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2fe90 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2fea0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
2feb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2fec0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2fed0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2fee0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
2fef0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
2ff00 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2ff10 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
2ff20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2ff30 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2ff40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2ff50 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
2ff60 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
2ff70 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2ff80 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
2ff90 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
2ffa0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
2ffb0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
2ffc0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2ffd0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2ffe0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
2fff0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
30000 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30010 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
30020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30030 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
30040 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
30050 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
30060 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
30070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
30080 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30090 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
300a0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
300b0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
300c0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
300d0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
300e0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
300f0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
30100 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
30110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
30120 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
30130 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
30140 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
30150 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
30160 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
30170 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
30180 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
30190 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
301a0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
301b0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
301c0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
301d0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
301e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
301f0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
30200 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
30210 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
30220 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
30230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30240 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30250 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
30260 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30270 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
30280 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
30290 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
302a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
302b0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
302c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
302d0 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
302e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
302f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30300 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
30310 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
30320 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
30330 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
30340 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
30350 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
30360 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
30370 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
30380 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30390 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
303a0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
303b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
303c0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
303d0 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
303e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
303f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
30400 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
30410 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
30420 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
30430 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30440 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
30450 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
30460 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
30470 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
30480 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
30490 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
304a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
304b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
304c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
304d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
304e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
304f0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
30500 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
30510 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
30520 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
30530 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
30540 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30550 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
30560 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
30570 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
30580 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
30590 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
305a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
305b0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
305c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
305d0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
305e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
305f0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
30600 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
30610 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
30620 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30630 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
30640 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30650 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
30660 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
30670 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
30680 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
30690 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
306a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
306b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
306c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
306d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
306e0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
306f0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
30700 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
30710 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30720 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30730 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
30740 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
30750 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
30760 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
30770 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
30780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30790 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
307a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
307b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
307c0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
307d0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
307e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
307f0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
30800 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
30810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30820 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
30830 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
30840 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
30850 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
30860 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
30870 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
30880 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
30890 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
308a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
308b0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
308c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
308d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
308e0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
308f0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
30900 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
30910 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
30920 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
30930 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  PI sqlite3 *sqli
30940 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
30950 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
30960 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
30970 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
30980 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
30990 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
309a0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
309b0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
309c0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
309d0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
309e0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
309f0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
30a00 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
30a10 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
30a20 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
30a30 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
30a40 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
30a50 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
30a60 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
30a70 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
30a80 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
30a90 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
30aa0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
30ab0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
30ac0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
30ad0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
30ae0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
30af0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
30b00 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
30b10 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
30b20 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
30b30 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
30b40 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
30b50 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
30b60 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
30b70 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
30b80 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
30b90 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
30ba0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
30bb0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
30bc0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
30bd0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
30be0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
30bf0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
30c00 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
30c10 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
30c20 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
30c30 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
30c40 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
30c50 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
30c60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
30c70 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
30c80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30c90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
30ca0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
30cb0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
30cc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30cd0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
30ce0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
30cf0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
30d00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30d10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
30d20 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
30d30 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
30d40 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
30d50 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
30d60 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
30d70 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
30d80 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
30d90 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
30da0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
30db0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
30dc0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
30dd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30de0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
30df0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
30e00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30e10 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
30e20 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
30e30 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
30e40 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
30e50 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
30e60 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
30e70 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
30e80 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
30e90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30ea0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
30eb0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
30ec0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
30ed0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
30ee0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
30ef0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
30f00 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
30f10 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
30f20 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
30f30 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
30f40 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
30f50 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
30f60 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
30f70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
30f80 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
30f90 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
30fa0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
30fb0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
30fc0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
30fd0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
30fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
30ff0 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
31000 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
31010 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
31020 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
31030 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
31040 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
31050 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
31060 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
31070 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
31080 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
31090 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
310a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
310b0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
310c0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
310d0 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
310e0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
310f0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
31100 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
31110 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
31120 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
31130 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
31140 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
31150 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
31160 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
31170 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
31180 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
31190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
311a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
311b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
311c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
311d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
311e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
311f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
31200 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31210 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
31220 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  ext*, int N);.SQ
31230 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
31240 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
31250 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
31260 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
31270 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
31280 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
31290 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
312a0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
312b0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
312c0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
312d0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
312e0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
312f0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
31300 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
31310 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
31320 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
31330 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
31340 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
31350 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
31360 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
31370 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
31380 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
31390 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
313a0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
313b0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
313c0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
313d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
313e0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
313f0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
31400 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
31410 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
31420 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
31430 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
31440 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
31450 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
31460 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
31470 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
31480 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
31490 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
314a0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
314b0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
314c0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
314d0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
314e0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
314f0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
31500 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
31510 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
31520 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
31530 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
31540 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
31550 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
31560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
31570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
31580 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
31590 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
315a0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
315b0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
315c0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
315d0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
315e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
315f0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
31600 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
31610 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
31620 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
31630 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31640 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
31650 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
31660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31670 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31680 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31690 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
316a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
316b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
316c0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
316d0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
316e0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
316f0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
31700 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
31710 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
31720 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
31730 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
31740 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
31750 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
31760 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
31770 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
31780 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
31790 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
317a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
317b0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
317c0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
317d0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
317e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
317f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
31800 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
31810 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
31820 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
31830 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
31840 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
31850 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
31860 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
31870 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
31880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31890 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
318a0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
318b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
318c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
318d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
318e0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
318f0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
31900 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
31910 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
31920 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
31930 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
31940 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
31950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31960 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
31970 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31980 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
31990 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
319a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
319b0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
319c0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
319d0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
319e0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
319f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31a00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31a10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
31a20 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
31a30 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
31a40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
31a50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
31a60 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
31a70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
31a80 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
31a90 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
31aa0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
31ab0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
31ac0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
31ad0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31ae0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
31af0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
31b00 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
31b10 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
31b20 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
31b30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
31b40 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
31b50 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
31b60 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
31b70 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
31b80 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
31b90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31ba0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
31bb0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
31bc0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
31bd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
31be0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
31bf0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
31c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31c10 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
31c20 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
31c30 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
31c40 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
31c50 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
31c60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
31c70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
31c80 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
31c90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31ca0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31cb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
31cc0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
31cd0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
31ce0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
31cf0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
31d00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
31d10 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
31d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
31d30 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
31d40 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
31d50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31d60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
31d70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
31d80 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
31d90 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
31da0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
31db0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
31dc0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
31dd0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
31de0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
31df0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
31e00 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
31e10 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
31e20 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
31e30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31e40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
31e50 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
31e60 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
31e70 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
31e80 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
31e90 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
31ea0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
31eb0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
31ec0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
31ed0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
31ee0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
31ef0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
31f00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31f10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31f20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31f30 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
31f40 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
31f50 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
31f60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31f70 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
31f80 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
31f90 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
31fa0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
31fb0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
31fc0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
31fd0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
31fe0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
31ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32000 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
32010 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
32020 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
32030 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
32040 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
32050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32060 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
32070 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32080 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
32090 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
320a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
320b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
320c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
320d0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
320e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
320f0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
32100 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
32110 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
32120 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
32130 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
32140 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
32150 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
32160 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32170 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32180 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
32190 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
321a0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
321b0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
321c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
321d0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
321e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
321f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
32200 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
32210 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32220 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
32230 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
32240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32250 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
32260 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
32270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32280 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
32290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
322a0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
322b0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
322c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
322d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
322e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
322f0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
32300 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
32310 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
32320 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
32330 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
32340 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
32350 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
32360 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
32370 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
32380 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
32390 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
323a0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
323b0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
323c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
323d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
323e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
323f0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
32400 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
32410 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32420 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
32430 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
32440 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
32450 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
32460 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
32470 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
32480 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
32490 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
324a0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
324b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
324c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
324d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
324e0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
324f0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
32500 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
32510 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
32520 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
32530 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
32540 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
32550 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
32560 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
32570 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
32580 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
32590 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
325a0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
325b0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
325c0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
325d0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
325e0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
325f0 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
32600 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
32610 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
32620 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
32630 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
32640 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
32650 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
32660 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
32670 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
32680 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
32690 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
326a0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
326b0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
326c0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
326d0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
326e0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
326f0 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
32700 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
32710 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
32720 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
32730 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
32740 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
32750 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32760 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
32770 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32780 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
32790 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
327a0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
327b0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
327c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
327d0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
327e0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
327f0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
32800 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
32810 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
32820 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
32830 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32840 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
32850 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
32860 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
32870 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
32880 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
32890 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
328a0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
328b0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
328c0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
328d0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
328e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
328f0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
32900 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
32910 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
32920 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
32930 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
32940 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
32950 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
32960 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
32970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32980 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32990 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
329a0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
329b0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
329c0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
329d0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
329e0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
329f0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
32a00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
32a10 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
32a20 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
32a30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
32a40 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
32a50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
32a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32a70 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
32a80 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
32a90 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
32aa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32ab0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
32ac0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
32ad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32ae0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32af0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
32b00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
32b10 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
32b20 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32b30 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
32b40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
32b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
32b60 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
32b70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
32b80 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
32b90 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
32ba0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
32bb0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
32bc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32bd0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
32be0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
32bf0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32c00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32c10 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
32c20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
32c30 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32c40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32c50 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
32c60 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
32c70 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
32c80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
32c90 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
32ca0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
32cb0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
32cc0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
32cd0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
32ce0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
32cf0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
32d00 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
32d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32d20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
32d30 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
32d40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
32d50 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
32d60 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
32d70 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
32d80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32d90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32da0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32db0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32dc0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32dd0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
32de0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32df0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
32e00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
32e10 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
32e20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32e30 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
32e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32e50 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
32e60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32e70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32e80 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
32e90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32ea0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
32eb0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32ec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32ed0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
32ee0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
32ef0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
32f00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32f10 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
32f20 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
32f30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
32f40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
32f50 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
32f60 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  xt*, int);.SQLIT
32f70 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
32f80 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
32f90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32fa0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
32fb0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
32fc0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
32fd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
32fe0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
32ff0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33000 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
33010 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33020 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
33030 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33040 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
33050 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33060 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
33070 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
33080 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33090 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
330a0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
330b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
330c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
330d0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
330e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
330f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
33100 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33110 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
33120 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
33130 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
33140 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33150 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
33160 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33170 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
33180 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
33190 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
331a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
331b0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
331c0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
331d0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
331e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
331f0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
33200 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33210 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
33220 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
33230 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
33240 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
33250 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
33260 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
33270 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
33280 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
33290 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
332a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
332b0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
332c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
332d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
332e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
332f0 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
33300 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
33310 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33320 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
33330 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33340 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
33350 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
33360 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
33370 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
33380 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33390 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
333a0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
333b0 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
333c0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
333d0 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
333e0 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
333f0 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
33400 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
33410 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
33420 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
33430 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
33440 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
33450 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
33460 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
33470 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
33480 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
33490 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
334a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
334b0 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
334c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
334d0 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
334e0 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
334f0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
33500 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
33510 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
33520 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
33530 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33540 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
33550 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
33560 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
33570 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
33580 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
33590 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
335a0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
335b0 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
335c0 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
335d0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
335e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
335f0 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
33600 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
33610 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
33620 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
33630 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
33640 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
33650 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
33660 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
33670 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
33680 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
33690 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
336a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
336b0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
336c0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
336d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
336e0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
336f0 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
33700 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
33710 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
33720 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
33730 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33740 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
33750 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
33760 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
33770 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
33780 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
33790 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
337a0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
337b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
337c0 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
337d0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
337e0 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
337f0 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
33800 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
33810 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
33820 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
33830 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
33840 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
33850 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
33860 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
33870 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
33880 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
33890 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
338a0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
338b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
338c0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
338d0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
338e0 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
338f0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
33900 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
33910 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
33920 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
33930 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
33940 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
33950 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
33960 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33970 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
33980 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
33990 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
339a0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
339b0 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
339c0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
339d0 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
339e0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
339f0 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
33a00 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
33a10 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33a20 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
33a30 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
33a40 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
33a50 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
33a60 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
33a70 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33a80 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
33a90 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
33aa0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
33ab0 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
33ac0 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
33ad0 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
33ae0 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
33af0 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
33b00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
33b10 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
33b20 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
33b30 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
33b40 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
33b50 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
33b60 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
33b70 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
33b80 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
33b90 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
33ba0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
33bb0 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
33bc0 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
33bd0 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
33be0 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
33bf0 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
33c00 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
33c10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
33c20 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
33c30 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
33c40 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
33c50 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
33c60 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
33c70 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
33c80 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
33c90 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
33ca0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
33cb0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
33cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33cd0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33ce0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
33cf0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
33d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
33d10 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
33d20 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
33d30 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
33d40 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
33d50 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
33d60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33d70 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
33d80 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
33d90 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
33da0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
33db0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
33dc0 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
33dd0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
33de0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
33df0 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
33e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33e10 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
33e20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
33e30 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
33e40 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
33e50 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
33e60 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
33e70 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
33e80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33e90 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
33ea0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
33eb0 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
33ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33ed0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
33ee0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
33ef0 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
33f00 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
33f10 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
33f20 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
33f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33f40 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
33f50 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
33f60 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
33f70 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
33f80 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
33f90 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
33fa0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
33fb0 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
33fc0 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
33fd0 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
33fe0 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
33ff0 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
34000 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
34010 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
34020 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
34030 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
34040 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
34050 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34060 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34070 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34080 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  16()]..*/.SQLITE
34090 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
340a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
340b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
340c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
340d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
340e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
340f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
34100 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34110 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34120 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
34130 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
34140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34150 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
34160 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
34170 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
34180 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
34190 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
341a0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
341b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
341c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
341d0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
341e0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
341f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
34200 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
34210 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
34220 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
34230 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
34240 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
34250 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
34260 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
34270 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34280 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34290 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
342a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
342b0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
342c0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
342d0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
342e0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
342f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
34300 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
34310 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
34320 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
34330 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
34340 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
34350 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
34360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34370 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
34380 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
34390 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
343a0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
343b0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
343c0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
343d0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
343e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
343f0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34400 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
34410 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
34420 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
34430 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
34440 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
34450 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
34460 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
34470 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34480 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
34490 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
344a0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
344b0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
344c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
344d0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
344e0 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
344f0 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
34500 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
34510 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
34520 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
34530 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
34540 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
34550 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
34560 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
34570 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
34580 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
34590 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
345a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
345b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
345c0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
345d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
345e0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
345f0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
34600 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
34610 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
34620 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
34630 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
34640 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
34650 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
34660 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
34670 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
34680 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
34690 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
346a0 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
346b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
346c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
346d0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
346e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
346f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
34700 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
34710 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
34720 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
34730 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
34740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34750 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
34760 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34770 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
34780 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34790 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
347a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
347b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
347c0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
347d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
347e0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
347f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
34800 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
34810 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  har*).);.SQLITE_
34820 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34830 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34840 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
34850 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
34860 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
34870 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
34880 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
34890 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
348a0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
348b0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
348c0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
348d0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
348e0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
348f0 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
34900 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
34910 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
34920 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
34930 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
34940 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
34950 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
34960 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
34970 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34980 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
34990 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
349a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
349b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
349c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
349d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
349e0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
349f0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
34a00 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
34a10 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
34a20 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
34a30 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
34a40 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
34a50 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
34a60 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
34a70 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
34a80 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
34a90 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34aa0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
34ab0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
34ac0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
34ad0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
34ae0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
34af0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
34b00 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
34b10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34b20 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
34b30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
34b40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
34b50 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
34b60 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
34b70 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
34b80 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
34b90 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
34ba0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
34bb0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
34bc0 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
34bd0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
34be0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
34bf0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
34c00 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
34c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
34c20 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
34c30 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
34c40 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
34c50 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
34c60 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
34c70 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
34c80 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
34c90 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
34ca0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
34cb0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
34cc0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
34cd0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
34ce0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
34cf0 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
34d00 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c  ill work..*/.SQL
34d10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
34d20 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
34d30 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
34d40 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
34d50 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
34d60 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
34d70 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
34d80 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
34d90 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
34da0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
34db0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
34dc0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
34dd0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
34de0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
34df0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
34e00 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
34e10 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
34e20 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
34e30 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
34e40 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
34e50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
34e60 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
34e70 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
34e80 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
34e90 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
34ea0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
34eb0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
34ec0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
34ed0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
34ee0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
34ef0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
34f00 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
34f10 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
34f20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
34f30 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
34f40 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
34f50 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
34f60 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
34f70 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
34f80 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
34f90 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
34fa0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
34fb0 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
34fc0 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
34fd0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
34fe0 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
34ff0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
35000 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
35010 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
35020 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
35030 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35040 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
35050 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
35060 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
35070 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
35080 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
35090 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
350a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
350b0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
350c0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
350d0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
350e0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
350f0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
35100 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
35110 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
35120 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
35130 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
35140 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
35150 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
35160 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
35170 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
35180 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
35190 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
351a0 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
351b0 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
351c0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
351d0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
351e0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
351f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
35200 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
35210 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
35220 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
35230 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
35240 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
35250 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
35260 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
35270 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35280 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
35290 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
352a0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
352b0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
352c0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
352d0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
352e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
352f0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
35300 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
35310 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
35320 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
35330 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
35340 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35350 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
35360 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
35370 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
35380 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
35390 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
353a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
353b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
353c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
353d0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
353e0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
353f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35400 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
35410 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
35420 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
35430 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
35440 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
35450 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
35460 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
35470 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
35480 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
35490 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
354a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
354b0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
354c0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
354d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
354e0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
354f0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
35500 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
35510 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35520 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
35530 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
35540 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
35550 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
35560 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
35570 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
35580 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
35590 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
355a0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
355b0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
355c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
355d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
355e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
355f0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
35600 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
35610 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
35620 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
35630 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
35640 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
35650 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
35660 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
35670 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
35680 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
35690 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
356a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
356b0 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  pen] or [sqlite3
356c0 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65  _open_v2].  Othe
356d0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
356e0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
356f0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
35700 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
35710 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65  es may fail.  He
35720 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d  re is an.** exam
35730 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f  ple of how to do
35740 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20   this using C++ 
35750 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73  with the Windows
35760 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20   Runtime:.**.** 
35770 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
35780 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61  >.** LPCWSTR zPa
35790 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74  th = Windows::St
357a0 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69  orage::Applicati
357b0 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d  onData::Current-
357c0 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  >.** &nbsp;     
357d0 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d  TemporaryFolder-
357e0 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a  >Path->Data();.*
357f0 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26  * char zPathBuf&
35800 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31  #91;MAX_PATH + 1
35810 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74  &#93;;.** memset
35820 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69  (zPathBuf, 0, si
35830 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b  zeof(zPathBuf));
35840 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75  .** WideCharToMu
35850 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c  ltiByte(CP_UTF8,
35860 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a   0, zPath, -1, z
35870 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28  PathBuf, sizeof(
35880 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e  zPathBuf),.** &n
35890 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e  bsp;     NULL, N
358a0 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33  ULL);.** sqlite3
358b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20  _temp_directory 
358c0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
358d0 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66  f("%s", zPathBuf
358e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
358f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c  ockquote>.*/.SQL
35900 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
35910 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
35920 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
35930 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
35940 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
35950 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35960 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
35970 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
35980 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35990 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
359a0 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
359b0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
359c0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
359d0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
359e0 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
359f0 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
35a00 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
35a10 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
35a20 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
35a30 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
35a40 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
35a50 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
35a60 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
35a70 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
35a80 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
35a90 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
35aa0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
35ab0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35ac0 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
35ad0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35ae0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
35af0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
35b00 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
35b10 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
35b20 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
35b30 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
35b40 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
35b50 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
35b60 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
35b70 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
35b80 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
35b90 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
35ba0 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
35bb0 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
35bc0 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
35bd0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
35be0 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
35bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35c00 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
35c10 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
35c20 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
35c30 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
35c40 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35c50 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35c60 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35c70 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35c80 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35c90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35ca0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35cb0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
35cc0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35cd0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
35ce0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
35cf0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
35d00 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
35d10 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
35d20 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
35d30 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
35d40 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
35d50 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35d60 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35d70 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35d80 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35d90 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35da0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35db0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35dc0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35dd0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35de0 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
35df0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35e00 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
35e10 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
35e20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
35e30 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
35e40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
35e50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35e60 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35e70 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35e80 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35e90 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35ea0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35eb0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35ec0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35ed0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35ee0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35ef0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35f00 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35f10 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
35f20 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
35f30 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
35f40 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
35f50 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
35f60 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
35f70 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
35f80 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
35f90 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
35fa0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
35fb0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
35fc0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35fd0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
35fe0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
35ff0 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
36000 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36010 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
36020 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
36030 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
36040 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
36050 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a  data_directory;.
36060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36070 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
36080 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
36090 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
360a0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
360b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
360c0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
360d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
360e0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
360f0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
36100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36110 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
36120 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
36130 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
36140 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
36150 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
36160 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
36170 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36180 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
36190 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
361a0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
361b0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
361c0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
361d0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
361e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
361f0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
36200 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
36210 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
36220 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
36230 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
36240 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
36250 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
36260 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
36270 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
36280 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
36290 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
362a0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
362b0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
362c0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
362d0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
362e0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
362f0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
36300 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
36310 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
36320 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
36330 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
36340 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
36350 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
36360 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
36370 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
36380 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
36390 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
363a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
363b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
363c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
363d0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
363e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
363f0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
36400 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36410 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
36420 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
36430 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
36440 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
36450 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
36460 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
36470 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
36480 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
36490 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
364a0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
364b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
364c0 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
364d0 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
364e0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
364f0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
36500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
36510 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
36520 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
36530 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
36540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36550 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
36560 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36570 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
36580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
36590 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
365a0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
365b0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
365c0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
365d0 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
365e0 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  place..*/.SQLITE
365f0 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
36600 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
36610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36630 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65   Return The File
36640 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62  name For A Datab
36650 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
36660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36670 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c  3_db_filename(D,
36680 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
36690 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
366a0 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  o a filename.** 
366b0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
366c0 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f  database N of co
366d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68  nnection D.  ^Th
366e0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
366f0 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20  file.** has the 
36700 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66  name "main".  If
36710 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74   there is no att
36720 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e  ached database N
36730 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
36740 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
36750 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65  , or if database
36760 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72   N is a temporar
36770 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y or in-memory d
36780 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a  atabase, then.**
36790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
367a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
367b0 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  ** ^The filename
367c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
367d0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  s function is th
367e0 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a  e output of the.
367f0 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  ** xFullPathname
36800 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
36810 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72  VFS].  ^In other
36820 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65   words, the file
36830 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  name.** will be 
36840 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
36850 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68  name, even if th
36860 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a  e filename used.
36870 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ** to open the d
36880 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c  atabase original
36890 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20  ly was a URI or 
368a0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
368b0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
368c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
368d0 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
368e0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
368f0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36900 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
36910 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69  REF: Determine i
36920 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  f a database is 
36930 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20  read-only.**.** 
36940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
36950 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e  readonly(D,N) in
36960 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36970 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  1 if the databas
36980 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63  e N.** of connec
36990 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f  tion D is read-o
369a0 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20  nly, 0 if it is 
369b0 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d  read/write, or -
369c0 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a  1 if N is not.**
369d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64   the name of a d
369e0 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65  atabase on conne
369f0 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49  ction D..*/.SQLI
36a00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36a10 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73  e3_db_readonly(s
36a20 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
36a30 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
36a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36a50 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
36a60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36a70 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
36a80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36a90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36aa0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
36ab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
36ac0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
36ad0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36af0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
36b00 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
36b10 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
36b20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
36b30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
36b40 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
36b50 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
36b60 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
36b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36b80 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
36b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36ba0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
36bb0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
36bc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
36bd0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
36be0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
36bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36c00 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
36c10 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
36c20 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
36c30 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
36c40 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
36c50 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
36c60 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
36c70 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
36c80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
36c90 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
36ca0 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
36cb0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
36cc0 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
36cd0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
36ce0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36cf0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
36d00 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
36d10 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
36d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
36d30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
36d40 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36d50 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
36d60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
36d70 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
36d80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
36d90 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
36da0 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
36db0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
36dc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
36dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
36de0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
36df0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
36e00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
36e10 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
36e20 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
36e30 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
36e40 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36e50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
36e60 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
36e70 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
36e80 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
36e90 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
36ea0 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
36eb0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
36ec0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
36ed0 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
36ee0 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
36ef0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
36f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36f10 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
36f20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
36f30 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
36f40 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
36f50 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
36f60 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
36f70 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
36f80 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
36f90 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
36fa0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
36fb0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
36fc0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
36fd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
36fe0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
36ff0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
37000 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
37010 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
37020 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
37030 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
37040 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
37050 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
37060 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
37070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37080 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
37090 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
370a0 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
370b0 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
370c0 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20   The commit and 
370d0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
370e0 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20  llbacks are not 
370f0 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68  reentrant..** Th
37100 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
37110 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
37120 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
37130 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
37140 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
37150 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
37160 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
37170 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
37180 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
37190 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
371a0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
371b0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
371c0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
371d0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
371e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
371f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
37200 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
37210 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
37220 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
37230 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
37240 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f  at running any o
37250 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65  ther SQL stateme
37260 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53  nts, including S
37270 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
37280 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63  ,.** or merely c
37290 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
372a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
372b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
372c0 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  )] will modify.*
372d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
372e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
372f0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
37300 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
37310 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
37320 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
37330 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
37340 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
37350 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
37360 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
37370 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
37380 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
37390 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
373a0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
373b0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
373c0 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
373d0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
373e0 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
373f0 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
37400 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
37410 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
37420 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
37430 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
37440 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
37450 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
37460 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
37470 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
37480 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
37490 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
374a0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
374b0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
374c0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
374d0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
374e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
374f0 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
37500 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
37510 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
37520 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
37530 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
37540 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
37550 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
37560 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
37570 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
37580 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
37590 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
375a0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
375b0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
375c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
375d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
375e0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
375f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37600 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
37610 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
37620 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
37630 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
37640 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
37650 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
37660 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
37670 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
37680 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
37690 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
376a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
376b0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
376c0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
376d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
376e0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
376f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
37700 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
37710 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
37720 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
37730 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
37740 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
37750 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
37760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37770 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
37780 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37790 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
377a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
377b0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
377c0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
377d0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
377e0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
377f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
37800 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
37810 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
37820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37830 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
37840 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
37850 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
37860 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
37870 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
37880 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
37890 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
378a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
378b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
378c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
378d0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
378e0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
378f0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
37900 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
37910 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
37920 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
37930 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37940 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
37950 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
37960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
37970 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
37980 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
37990 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
379a0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
379b0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
379c0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
379d0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
379e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
379f0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
37a00 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
37a10 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
37a20 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
37a30 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
37a40 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
37a50 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
37a60 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
37a70 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
37a80 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
37a90 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
37aa0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
37ab0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
37ac0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
37ad0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
37ae0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
37af0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
37b00 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
37b10 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
37b20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
37b30 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
37b40 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
37b50 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
37b60 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
37b70 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
37b80 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
37b90 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
37ba0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
37bb0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
37bc0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
37bd0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
37be0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
37bf0 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
37c00 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
37c10 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
37c20 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
37c30 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
37c40 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
37c50 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
37c60 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
37c70 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
37c80 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
37c90 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
37ca0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
37cb0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
37cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37cd0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
37ce0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
37cf0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
37d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
37d20 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
37d30 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
37d40 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
37d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d60 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
37d70 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
37d80 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
37d90 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37da0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
37db0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
37dc0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
37dd0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
37de0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
37df0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
37e00 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
37e10 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
37e20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
37e30 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
37e40 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
37e50 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
37e60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37e70 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37e80 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
37e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
37ea0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
37eb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
37ec0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
37ed0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37ee0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
37ef0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
37f00 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
37f10 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
37f20 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37f30 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
37f40 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37f50 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
37f60 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
37f70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
37f80 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
37f90 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
37fa0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
37fb0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
37fc0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
37fd0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
37fe0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
37ff0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
38000 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
38010 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20  ger Cache.**.** 
38020 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
38030 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
38040 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
38050 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
38060 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
38070 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
38080 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
38090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
380a0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
380b0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
380c0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
380d0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
380e0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
380f0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
38100 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
38110 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
38120 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
38130 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
38140 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
38150 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
38160 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
38170 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
38180 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
38190 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
381a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
381b0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
381c0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
381d0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
381e0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
381f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
38200 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
38210 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
38220 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
38230 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
38240 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
38250 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
38260 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
38270 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
38280 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
38290 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
382a0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
382b0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
382c0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
382d0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
382e0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
382f0 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
38300 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
38310 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
38320 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
38330 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
38340 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
38350 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
38360 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
38370 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
38380 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
38390 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
383a0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
383b0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
383c0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
383d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
383e0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
383f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
38400 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
38410 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
38420 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
38430 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
38440 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
38450 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
38460 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Mode].*/.SQLITE_
38470 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38480 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38490 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
384a0 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
384b0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
384c0 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
384d0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
384e0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
384f0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
38500 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
38510 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
38520 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
38530 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
38540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
38550 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
38560 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
38570 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
38580 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38590 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
385a0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
385b0 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
385c0 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
385d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
385e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
385f0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
38600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
38610 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
38620 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
38630 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
38640 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
38650 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
38660 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
38670 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
38680 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
38690 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
386a0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
386b0 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
386c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
386d0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
386e0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  T]..**.** See al
386f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  so: [sqlite3_db_
38700 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
38710 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
38720 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
38730 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
38740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38750 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73  : Free Memory Us
38760 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65  ed By A Database
38770 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
38780 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
38790 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
387a0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  (D) interface at
387b0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61  tempts to free a
387c0 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d  s much heap