System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f8c7739dd733f6e57878c8f192542faa41835636:


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 33 22 0a 23 64 65 66 69 6e 65 20 53  .7.13".#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 33 0a 23 64 65  MBER 3007013.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 36 2d 30 38 20 31 34 3a 30 31 3a 35 33 20  -06-08 14:01:53 
1080: 30 32 35 32 32 37 62 65 35 34 39 35 66 39 35 30  025227be5495f950
1090: 63 34 36 36 64 66 61 62 61 63 31 34 30 63 62 61  c466dfabac140cba
10a0: 36 39 65 34 39 38 62 65 22 0a 0a 2f 2a 0a 2a 2a  69e498be"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20  _close()].** is 
2490: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
24a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
24b0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
24c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
24f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2520: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2530: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2540: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2550: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2560: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2570: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2590: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
25e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
25f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2600: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2610: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2620: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2630: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2640: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2650: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2670: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2680: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2690: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
26e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
26f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2700: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2710: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2720: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2730: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2740: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2750: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2760: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2770: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2780: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2790: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
27e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
27f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2800: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2810: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2820: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2830: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2850: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2860: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2870: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2880: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2890: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
28e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
28f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2900: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2910: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2920: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2930: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2940: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2950: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2960: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2970: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2980: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2990: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29a0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29b0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29c0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29d0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
29e0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
29f0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2a80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2a90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2aa0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ab0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ac0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2ad0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2ae0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2af0: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b20: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  K if the [sqlite
2b30: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  3] object is.** 
2b40: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2b50: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2b60: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72  ssociated resour
2b70: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2b80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ted..**.** Appli
2b90: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71  cations must [sq
2ba0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2bb0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
2bc0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
2be0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2bf0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2c00: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
2c10: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
2c20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2c30: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
2c40: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
2c50: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
2c60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
2c70: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  se() is called o
2c80: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2c90: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
2ca0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
2cb0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
2cc0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72  d statements] or
2cd0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2ce0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2cf0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
2d00: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69  .**.** ^If [sqli
2d10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2d20: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2d30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2d40: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
2d50: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
2d60: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d70: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2d80: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2d90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2da0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2db0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2dc0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2dd0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2de0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2e00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2e10: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
2e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2e30: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
2e40: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
2e50: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
2e60: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20  e3_close() with 
2e70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2e80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a  rgument is a .**
2e90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2ea0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2eb0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2ec0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2ed0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2ee0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2ef0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2f00: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2f10: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2f20: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
2f30: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
2f40: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
2f50: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
2f60: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
2f70: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2f80: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2f90: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2fa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2fb0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2fc0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fe0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
2ff0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
3000: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
3010: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
3020: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
3030: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3050: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3060: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3070: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3080: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3090: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
30a0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
30b0: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
30c0: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
30d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
30e0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
30f0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
3100: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
3110: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
3120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3130: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3140: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3150: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3160: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3180: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3190: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
31a0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
31b0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
31c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
31d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
31e0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
31f0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
3200: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
3210: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
3220: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
3230: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3240: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3250: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3260: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3270: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3280: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3290: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
32a0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
32b0: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
32c0: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
32d0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
32e0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
32f0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
3300: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
3310: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
3320: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
3330: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3340: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3350: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3360: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3370: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3380: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3390: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
33a0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
33b0: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
33c0: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
33d0: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
33e0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
33f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3400: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
3410: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
3420: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
3430: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3440: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3450: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3460: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3470: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3480: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3490: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
34a0: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
34b0: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
34c0: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
34d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34e0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
34f0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3500: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3510: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3520: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  of.** of sqlite3
3530: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68  _exec() after th
3540: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3550: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e  string is no lon
3560: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e  ger needed..** ^
3570: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
3580: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3590: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
35a0: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73  LL and no errors
35b0: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20  .** occur, then 
35c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73  sqlite3_exec() s
35d0: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ets the pointer 
35e0: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d  in its 5th param
35f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20  eter to.** NULL 
3600: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
3610: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73  ..**.** ^If an s
3620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3630: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
3640: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c  on-zero, the sql
3650: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72  ite3_exec().** r
3660: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
3670: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68  QLITE_ABORT with
3680: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  out invoking the
3690: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20   callback again 
36a0: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72  and.** without r
36b0: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65  unning any subse
36c0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
36d0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
36e0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   2nd argument to
36f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3700: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  c() callback fun
3710: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20  ction is the.** 
3720: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
3730: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  s in the result.
3740: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d    ^The 3rd argum
3750: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3760: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c  e3_exec().** cal
3770: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3780: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3790: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65   strings obtaine
37a0: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20  d as if from.** 
37b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37c0: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72  text()], one for
37d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e   each column.  ^
37e0: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66  If an element of
37f0: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77   a.** result row
3800: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
3810: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
3820: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66  string pointer f
3830: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  or the.** sqlite
3840: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3850: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  k is a NULL poin
3860: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61  ter.  ^The 4th a
3870: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
3880: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3890: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
38a0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
38b0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65  s to strings whe
38c0: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79  re each.** entry
38d0: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20   represents the 
38e0: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f  name of correspo
38f0: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c  nding result col
3900: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a  umn as obtained.
3910: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3920: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
3930: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32  .**.** ^If the 2
3940: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3950: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3970: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  , a pointer.** t
3980: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
3990: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  g, or a pointer 
39a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  that contains on
39b0: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
39c0: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d  d/or .** SQL com
39d0: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
39e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
39f0: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
3a00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
3a10: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
3a20: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f  **.** Restrictio
3a30: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ns:.**.** <ul>.*
3a40: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75  cation must insu
3a60: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20  re that the 1st 
3a70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20  ite3_exec().**  
3a90: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61      is a valid a
3aa0: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  nd open [databas
3ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3ac0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3ad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3ae0: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20  close [database 
3af0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3b00: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3b10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3b20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b30: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3b50: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3b60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3b70: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3b80: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3b90: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3ba0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3bb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3bd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3be0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3bf0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
3c00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
3c10: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3c20: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3c50: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3c60: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3c90: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3ca0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3cb0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3cc0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3cd0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3ce0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d10: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3d20: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3d30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3d40: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
3d70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
3d80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3d90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3da0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
3db0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
3dc0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
3dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
3de0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
3df0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
3e00: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
3e10: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
3e20: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
3e30: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
3e40: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
3e50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
3e60: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
3f00: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
3f10: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
3f20: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
3f30: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
3f40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3f50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3f60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3f70: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3f80: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3fa0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3fb0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3fc0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3fd0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3fe0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3ff0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4000: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4010: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4030: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
4040: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
4050: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4060: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4070: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4080: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4090: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
40a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40b0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
40c0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
40d0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
40e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4100: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4110: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4120: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
4140: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
4150: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
4160: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4180: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4190: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
41a0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
41b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41c0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
41d0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
41e0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
41f0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4220: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4230: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
4240: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
4250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
4260: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4270: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4280: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4290: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
42a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
42b0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
42c0: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
42d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
42e0: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
42f0: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4300: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4310: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4320: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4330: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
4340: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
4350: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
4360: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4370: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
4390: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
43a0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
43b0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
43c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43d0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
43e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
43f0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4400: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4410: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4420: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4430: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
4450: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
4460: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
4470: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
44a0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
44b0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
44c0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
44e0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
44f0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4520: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4530: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
4560: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
4570: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
4580: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
45a0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
45b0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
45c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
45d0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
45e0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
45f0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4600: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4630: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4640: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4650: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4680: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4690: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
46a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46c0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
46d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
46e0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
46f0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4710: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4720: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4730: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4740: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4750: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4770: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4780: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
47a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
47b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
47d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
47e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
47f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
4850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
4860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
48a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
48b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
48c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
48d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
48e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
48f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
49a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
49b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
49c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
49d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
49e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
4a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
4a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
4a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
4a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
4a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
4a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
4a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
4ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
4ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
4af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
4b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
4b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
4cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
4cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
4dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
4ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
4f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
4f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
4fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
4fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
4fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5010: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5020: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5030: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5050: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
5060: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5070: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
50c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
50e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5110: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5130: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5140: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5150: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5160: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5170: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
51e0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
51f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5210: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5220: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5230: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5240: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5250: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5260: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5270: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5280: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
52a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
52b0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
52c0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
52d0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
52e0: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
52f0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5300: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5310: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5320: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5330: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5340: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a  T | (2<<8))../*.
5350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5360: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5370: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5380: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5390: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
53a0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
53b0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
53c0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
53e0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
53f0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5410: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5420: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5430: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5440: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5450: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5460: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5470: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5480: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5490: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
54a0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
54b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
54c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
54d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
54e0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
54f0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5500: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5510: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5530: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5540: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5550: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5560: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5570: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5580: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5590: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
55a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
55b0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
55c0: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
55d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
55e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5600: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5610: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5620: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5630: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5640: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5650: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5660: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5670: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5680: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5690: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
56a0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
56b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
56c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
56d0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
56e0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
56f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5700: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5710: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5720: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
5730: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5750: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5760: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
5770: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5780: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5790: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
57a0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
57b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
57c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
57d0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
57e0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
57f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5800: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5810: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
5820: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
5830: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5840: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
5850: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
5860: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
5870: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5880: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5890: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
58a0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
58b0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
58c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
58d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
58e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
58f0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
5900: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
5910: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5920: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5930: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
5940: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
5950: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
5960: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5970: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5980: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
5990: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
59a0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
59b0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
59c0: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
59d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
59e0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
59f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5a00: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5a10: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5a20: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
5a30: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
5a40: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
5a50: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
5a60: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
5a70: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
5a80: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
5a90: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
5aa0: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
5ab0: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
5ac0: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
5ad0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
5ae0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
5af0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
5b00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5b10: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
5b20: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
5b30: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
5b40: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
5b50: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
5b60: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
5b70: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
5b80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
5b90: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
5ba0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
5bb0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
5bc0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
5bd0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
5be0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
5bf0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
5c00: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
5c10: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
5c20: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
5c30: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5c40: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
5c50: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
5c60: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
5c70: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
5c80: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
5c90: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
5ca0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
5cb0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
5cc0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
5cd0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
5ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5cf0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
5d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
5d20: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
5d30: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
5d40: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
5d50: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
5d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
5d70: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
5d80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d90: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
5da0: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
5db0: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
5dc0: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
5dd0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
5de0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
5df0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
5e00: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
5e10: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
5e20: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
5e30: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
5e40: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
5e50: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
5e60: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
5e70: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
5e80: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5e90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5eb0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5ec0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ed0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5ee0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ef0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5f00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f20: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5f30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f40: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f70: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5f80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f90: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5fb0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5fc0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5fe0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5ff0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6000: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
6010: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6020: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
6030: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
6040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6050: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6060: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6070: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6080: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6090: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
60a0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
60b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
60c0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
60d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6100: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
6110: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
6120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6130: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6140: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a      0x00001000..
6150: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6160: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6170: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6180: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6190: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
61a0: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
61b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
61c0: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
61d0: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
61e0: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
61f0: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6200: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6210: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6220: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6230: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6250: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6260: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6270: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6280: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6290: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
62a0: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
62b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
62c0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
62d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
62e0: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
62f0: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6300: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6310: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6320: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6330: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6340: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6350: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6360: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6370: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6380: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6390: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
63a0: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
63b0: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
63c0: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
63d0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
63e0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
63f0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6400: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6410: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6430: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6440: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6450: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6460: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6470: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6480: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6490: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
64a0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
64b0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
64c0: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
64d0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
64e0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
64f0: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6500: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6510: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6520: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6530: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6540: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6560: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6570: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6580: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6590: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
65a0: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
65b0: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
65c0: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
65d0: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
65e0: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
65f0: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6600: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6610: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6620: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6630: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6640: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6650: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6660: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
6670: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
6680: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
6690: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
66a0: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
66b0: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
66c0: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
66d0: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
66e0: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
66f0: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
6700: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
6710: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
6720: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
6730: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
6740: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
6750: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6760: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6770: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
6780: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
6790: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
67a0: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
67b0: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
67c0: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
67d0: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
67e0: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
67f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6800: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
6810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6820: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
6830: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
6840: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
6850: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6860: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6870: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6880: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6890: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
68a0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
68b0: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
68c0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
68d0: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
68e0: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
68f0: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
6900: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
6910: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
6920: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
6930: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
6940: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
6950: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
6960: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
6970: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
6980: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
6990: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
69a0: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
69b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
69c0: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
69d0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
69e0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
69f0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
6a00: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
6a10: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
6a30: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
6a40: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
6a50: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
6a60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6a70: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
6a80: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
6a90: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
6aa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6ab0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
6ac0: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
6ad0: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
6ae0: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
6af0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6b00: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6b10: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
6b20: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
6b30: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
6b40: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6b50: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6b60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6b70: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6b80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6b90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6bb0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6bc0: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6bd0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6be0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
6bf0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
6c00: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
6c10: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
6c20: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6c30: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
6c40: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6c50: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
6c60: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
6c70: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
6c80: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
6c90: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
6ca0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
6cb0: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
6cc0: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
6cd0: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
6ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6cf0: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
6d00: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6d10: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6d20: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6d30: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6d40: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6d50: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6d60: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
6d70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6d80: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
6d90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6da0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
6db0: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
6dc0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
6dd0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
6de0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
6df0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
6e00: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
6e10: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
6e20: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
6e30: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
6e40: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
6e50: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
6e60: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e70: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
6e80: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6e90: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6ea0: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6eb0: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6ec0: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6ed0: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6ee0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6ef0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6f00: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6f10: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6f20: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6f30: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
6f40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6f50: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
6f60: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6f70: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6f80: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6f90: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6fa0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6fb0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6fc0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6fd0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6fe0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6ff0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7000: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
7010: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
7020: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
7030: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
7040: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
7050: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
7060: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7070: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7080: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7090: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
70a0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
70b0: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
70c0: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
70d0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
70e0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
70f0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7100: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7110: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7120: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7130: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7140: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7150: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7160: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7170: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7180: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7190: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
71a0: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
71b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
71c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
71d0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
71e0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
71f0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7200: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7210: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7220: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7230: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7240: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7250: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7260: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7270: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7280: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7290: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
72a0: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
72b0: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
72c0: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
72d0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
72e0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
72f0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7300: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7310: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7320: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7330: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7340: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7350: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7360: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7370: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7380: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7390: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
73a0: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
73b0: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
73c0: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
73d0: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
73e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
73f0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
7400: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
7410: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
7420: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7430: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7440: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7450: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7460: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7470: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7480: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7490: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
74a0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
74b0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
74c0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
74d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
74e0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
74f0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
7500: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
7510: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
7520: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
7530: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
7540: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
7550: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
7560: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
7570: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
7580: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
7590: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
75a0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
75b0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
75c0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
75d0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
75e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
75f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7600: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
7610: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
7620: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
7630: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
7640: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7650: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7660: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
7670: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7680: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
7690: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76a0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
76b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76c0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
76d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76e0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
76f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7700: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
7710: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7720: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
7730: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7740: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
7750: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7760: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
7770: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7780: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7790: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
77a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
77b0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
77c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
77d0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
77e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
77f0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
7800: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
7810: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
7820: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
7830: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
7840: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
7850: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
7860: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
7870: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
7880: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
7890: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
78a0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
78b0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
78c0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
78d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
78e0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
78f0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
7900: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
7910: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
7920: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
7930: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
7940: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
7950: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
7960: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
7970: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
7980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7990: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
79a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
79b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
79c0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
79d0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
79e0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
79f0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
7a00: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
7a10: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
7a20: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
7a30: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
7a40: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
7a50: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
7a60: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
7a70: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
7a80: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
7a90: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
7aa0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
7ab0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
7ac0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
7ad0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7ae0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
7af0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
7b00: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
7b10: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7b20: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7b30: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
7b40: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
7b50: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7b60: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
7b70: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
7b80: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
7b90: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
7ba0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
7bb0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
7bc0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
7bd0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7be0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
7bf0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
7c00: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
7c10: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
7c20: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
7c30: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
7c40: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7c50: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
7c60: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
7c70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7c80: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
7c90: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
7ca0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
7cb0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
7cc0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
7cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7ce0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
7cf0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
7d00: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
7d10: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
7d20: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
7d30: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
7d40: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
7d50: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
7d60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
7d70: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
7d80: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
7d90: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7da0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
7db0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
7dc0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
7dd0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
7de0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7df0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
7e00: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
7e10: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7e20: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
7e30: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
7e40: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
7e50: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
7e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7e70: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
7e80: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
7e90: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
7ea0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7eb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
7ec0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
7ed0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
7ee0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
7ef0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7f00: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
7f10: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
7f20: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7f30: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
7f40: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
7f50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7f60: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
7f70: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
7f80: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7f90: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
7fa0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
7fb0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7fc0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7fd0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7fe0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7ff0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8000: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8010: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8020: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8030: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8040: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8050: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8060: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8070: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8080: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8090: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
80a0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
80b0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
80c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
80d0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
80e0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
80f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8100: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8110: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8120: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8130: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8140: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8150: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8160: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8170: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8180: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8190: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
81a0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
81b0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
81c0: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
81d0: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
81e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
81f0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8200: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8210: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8220: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8230: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8240: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8250: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8260: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8270: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8280: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8290: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
82a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
82b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
82c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
82d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
82e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
82f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8300: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8310: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8330: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8340: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8350: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8360: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8370: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8380: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8390: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
83a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
83b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
83c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
83d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
83e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
83f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8400: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8410: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8420: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8430: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8440: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8450: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8460: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8470: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8480: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8490: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
84a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
84b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
84c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
84d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
84e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
84f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8500: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8510: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8520: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8530: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8540: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8550: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8560: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8570: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8580: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
8590: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
85a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
85b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
85c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
85d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
85e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
85f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
8600: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
8610: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
8620: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
8630: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
8640: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
8650: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8660: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
8670: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
8680: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
8690: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
86a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
86b0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
86c0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
86d0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
86e0: 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  ED] opcode is ge
86f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
8700: 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20  ly by.** SQLite 
8710: 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20  and sent to all 
8720: 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  VFSes in place o
8730: 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20  f a call to the 
8740: 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20  xSync method.** 
8750: 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
8760: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73  e connection has
8770: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
8780: 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46  nous] set to OFF
8790: 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63  .)^.** Some spec
87a0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65  ialized VFSes ne
87b0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69  ed this signal i
87c0: 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61  n order to opera
87d0: 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20  te correctly.** 
87e0: 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e  when [PRAGMA syn
87f0: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
8800: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
8810: 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d  F] is set, but m
8820: 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f  ost .** VFSes do
8830: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
8840: 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64  ignal and should
8850: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
8860: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
8870: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
8880: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
8890: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
88a0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
88b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  .** opcode as do
88c0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
88d0: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
88e0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
88f0: 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61  zed VFSes.** tha
8900: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
8910: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
8920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
8930: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
8940: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
8950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
8960: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
8970: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
8980: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
8990: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
89a0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
89b0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
89c0: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
89d0: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
89e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
89f0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
8a00: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
8a10: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
8a20: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
8a30: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
8a40: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
8a50: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
8a60: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
8a70: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
8a80: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
8a90: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
8aa0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
8ab0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
8ac0: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
8ad0: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
8ae0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
8af0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
8b00: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
8b10: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
8b20: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
8b30: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
8b40: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
8b50: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
8b60: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
8b70: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
8b80: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
8b90: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
8ba0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
8bb0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
8bc0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
8bd0: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
8be0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
8bf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
8c00: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
8c10: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
8c20: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
8c30: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
8c40: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
8c50: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
8c60: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
8c70: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
8c80: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
8c90: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
8ca0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
8cb0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
8cc0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
8cd0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
8ce0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
8cf0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
8d00: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
8d10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
8d20: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
8d30: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
8d40: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
8d50: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
8d60: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
8d70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
8d80: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
8d90: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
8da0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
8db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8dc0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
8dd0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
8de0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
8df0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
8e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e10: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
8e20: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
8e30: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
8e40: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
8e50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
8e60: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
8e70: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
8e80: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
8e90: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
8ea0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8eb0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
8ec0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
8ed0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
8ee0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
8ef0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
8f00: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
8f10: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
8f20: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
8f30: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
8f40: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
8f50: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
8f60: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
8f70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
8f80: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
8f90: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
8fa0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
8fb0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
8fc0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8fd0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
8fe0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
8ff0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
9000: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
9010: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9020: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9030: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
9040: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9050: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9060: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9070: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9080: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9090: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
90a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
90b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
90c0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
90d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
90e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
90f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
9100: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
9110: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
9120: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
9130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9140: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9150: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
9170: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
9180: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9190: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
91a0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
91b0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
91c0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
91d0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
91e0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
91f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
9200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
9210: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9220: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
9230: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
9240: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
9250: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9260: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9270: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9280: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
9290: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
92a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
92b0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
92c0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
92d0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
92e0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
92f0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
9300: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
9310: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
9320: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
9330: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
9340: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
9350: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
9360: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
9370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9380: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
9390: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
93a0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
93b0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
93c0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
93d0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
93e0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
93f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
9400: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
9410: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
9420: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
9430: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
9440: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
9450: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
9460: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
9470: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
9480: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
9490: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
94a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94b0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
94c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
94d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
94e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
94f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
9500: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
9510: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
9520: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
9530: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
9540: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
9550: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
9560: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
9570: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
9580: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
9590: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
95a0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
95b0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
95c0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
95d0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
95e0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
95f0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
9600: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9610: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
9620: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
9630: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
9640: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
9650: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
9660: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
9670: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
9680: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
9690: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
96a0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
96b0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
96c0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
96d0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
96e0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
96f0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
9700: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
9710: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9720: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
9730: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
9740: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
9750: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
9760: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
9770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9780: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
9790: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
97a0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
97b0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
97d0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
97e0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
97f0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
9800: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
9810: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
9820: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
9830: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
9840: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
9850: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
9860: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
9870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9880: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
9890: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
98a0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
98b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
98c0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
98d0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
98e0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
98f0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
9900: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
9910: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
9920: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
9930: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
9940: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
9950: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
9960: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
9970: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
9980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9990: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
99a0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
99b0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
99c0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
99d0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
99e0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
99f0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
9a00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
9a10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
9a20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
9a30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
9a40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
9a50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
9a60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
9a70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
9a80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
9a90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
9aa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9ab0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
9ac0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
9ad0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
9ae0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
9af0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
9b00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
9b10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9b20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
9b30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
9b40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
9b50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
9b60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
9b70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
9b80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
9b90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
9ba0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
9bb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
9bc0: 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  atement.  ^If th
9bd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9be0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9bf0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
9c00: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
9c10: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9c20: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
9c30: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
9c40: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
9c50: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
9c60: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
9c70: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
9c80: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
9c90: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
9ca0: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
9cb0: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
9cc0: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
9cd0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
9ce0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
9cf0: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
9d00: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
9d10: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
9d20: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
9d30: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
9d40: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
9d50: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
9d60: 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  s..** </ul>.*/.#
9d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9d80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
9d90: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
9da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
9db0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
9dc0: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
9dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
9de0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
9df0: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
9e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
9e10: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
9e20: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
9e30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9e40: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
9e50: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
9e60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
9e70: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9e80: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
9e90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
9ea0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
9eb0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
9ec0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9ed0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
9ee0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
9ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9f00: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
9f10: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
9f20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9f30: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
9f40: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
9f50: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9f60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
9f70: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
9f80: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9fa0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
9fb0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9fc0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
9fd0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
9fe0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
9ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
a000: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a010: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
a020: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
a030: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
a040: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
a050: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
a060: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
a070: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
a080: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
a090: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
a0a0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
a0b0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
a0c0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
a0d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
a0e0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
a0f0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
a100: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
a110: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
a120: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
a130: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
a140: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
a150: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
a160: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a170: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
a180: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
a190: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
a1a0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
a1b0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
a1c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
a1d0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
a1e0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
a1f0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
a200: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
a210: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
a220: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
a230: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
a240: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
a250: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
a260: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
a270: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
a280: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
a290: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
a2a0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
a2b0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
a2c0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
a2d0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
a2e0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
a2f0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
a300: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
a310: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
a320: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
a330: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
a340: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
a350: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
a360: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
a370: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
a380: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
a390: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
a3a0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a3b0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
a3c0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
a3d0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
a3e0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
a3f0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
a400: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
a410: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
a420: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
a430: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
a440: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
a450: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
a460: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
a470: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
a480: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
a490: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
a4a0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
a4b0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
a4c0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
a4d0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
a4e0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
a4f0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
a500: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
a510: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
a520: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
a530: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
a540: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
a550: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
a560: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
a570: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
a580: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
a590: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
a5a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
a5b0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
a5c0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
a5d0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
a5e0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a5f0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
a600: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
a610: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
a620: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
a630: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
a640: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
a650: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
a660: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
a670: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
a680: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
a690: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
a6a0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
a6b0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
a6c0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
a6d0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
a6e0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
a6f0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
a700: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a710: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
a720: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
a730: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
a740: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
a750: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
a760: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
a770: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
a780: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
a790: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
a7a0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
a7b0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
a7c0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
a7d0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
a7e0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
a7f0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
a800: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
a810: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
a820: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
a830: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
a840: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
a850: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
a860: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
a870: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
a880: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
a890: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
a8a0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
a8b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a8c0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
a8d0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
a8e0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
a8f0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
a900: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
a910: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
a920: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
a930: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
a940: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
a950: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
a960: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
a970: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
a980: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
a990: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
a9a0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
a9b0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
a9c0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
a9d0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
a9e0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
a9f0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
aa00: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
aa10: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
aa20: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
aa30: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
aa40: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
aa50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
aa60: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
aa70: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
aa80: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
aa90: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
aaa0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
aab0: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
aac0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
aad0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
aae0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
aaf0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
ab00: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
ab10: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
ab20: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
ab30: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
ab40: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
ab50: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
ab60: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
ab70: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
ab80: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
ab90: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
aba0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
abb0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
abc0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
abd0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
abe0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
abf0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
ac00: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
ac10: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
ac20: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
ac30: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
ac40: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
ac50: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ac60: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
ac70: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ac80: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ac90: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
aca0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
acb0: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
acc0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
acd0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
ace0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
acf0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
ad00: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
ad10: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
ad20: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
ad30: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
ad40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
ad50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
ad60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ad70: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
ad80: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ad90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ada0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
adb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
adc0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
add0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ade0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
adf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ae00: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
ae10: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ae20: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ae30: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ae40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ae50: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ae60: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
ae70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ae80: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
ae90: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
aea0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
aeb0: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
aec0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
aed0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
aee0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
aef0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
af00: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
af10: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
af20: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
af30: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
af40: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
af50: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
af60: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
af70: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
af80: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
af90: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
afa0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
afb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
afc0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
afd0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
afe0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
aff0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
b000: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
b010: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
b020: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
b030: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
b040: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
b050: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
b060: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
b070: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
b080: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
b090: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
b0a0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
b0b0: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
b0c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
b0d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b0e0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
b0f0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
b100: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
b110: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
b120: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
b130: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
b140: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
b150: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
b160: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
b170: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
b180: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
b190: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
b1a0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
b1b0: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
b1c0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
b1d0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
b1e0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
b1f0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
b200: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
b210: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
b220: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
b230: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
b240: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
b250: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
b260: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
b270: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
b280: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
b290: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
b2a0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
b2b0: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
b2c0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
b2d0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
b2e0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
b2f0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
b300: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
b310: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
b320: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
b330: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
b340: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
b350: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
b360: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
b370: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
b380: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
b390: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
b3a0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
b3b0: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
b3c0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
b3d0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
b3e0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
b3f0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
b400: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
b410: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
b420: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
b430: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
b440: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
b450: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
b460: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
b470: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
b480: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
b490: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
b4a0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
b4b0: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
b4c0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
b4d0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b4e0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
b4f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
b500: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
b510: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
b520: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
b530: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
b540: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
b550: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
b560: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
b570: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
b580: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
b590: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
b5a0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
b5b0: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
b5c0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
b5d0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
b5e0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
b5f0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
b600: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
b610: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
b620: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
b630: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
b640: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
b650: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
b660: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
b670: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
b680: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
b690: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
b6a0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
b6b0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
b6c0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
b6d0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
b6e0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
b6f0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
b700: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
b710: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
b720: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
b730: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
b740: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
b750: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
b760: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
b770: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
b780: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
b790: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
b7a0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
b7b0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
b7c0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
b7d0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
b7e0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
b7f0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
b800: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
b810: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
b820: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
b830: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
b840: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
b850: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
b860: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
b870: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
b880: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
b890: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
b8a0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
b8b0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
b8c0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
b8d0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
b8e0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
b8f0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
b900: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
b910: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
b920: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
b930: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
b940: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
b950: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
b960: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
b970: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
b980: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
b990: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
b9a0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
b9b0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
b9c0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
b9d0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
b9e0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
b9f0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
ba00: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
ba10: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
ba20: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
ba30: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
ba40: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
ba50: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
ba60: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
ba70: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
ba80: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
ba90: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
baa0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
bab0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
bac0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
bad0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
bae0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
baf0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
bb00: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
bb10: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
bb20: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
bb30: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
bb40: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
bb50: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
bb60: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bb70: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
bb80: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
bb90: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
bba0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
bbb0: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
bbc0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
bbd0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
bbe0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
bbf0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
bc00: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
bc10: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bc20: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
bc30: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
bc40: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
bc50: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
bc60: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
bc70: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
bc80: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
bc90: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
bca0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
bcb0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
bcc0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
bcd0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
bce0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
bcf0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
bd00: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
bd10: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
bd20: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
bd30: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
bd40: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
bd50: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
bd60: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
bd70: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
bd80: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
bd90: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
bda0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
bdb0: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
bdc0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
bdd0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
bde0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
bdf0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
be00: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
be10: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
be20: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
be30: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
be40: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
be50: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
be60: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
be70: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
be80: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
be90: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
bea0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
beb0: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
bec0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
bed0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
bee0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
bef0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
bf00: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
bf10: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
bf20: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
bf30: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
bf40: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
bf50: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
bf60: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
bf70: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
bf80: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
bf90: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
bfa0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
bfb0: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
bfc0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
bfd0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
bfe0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
bff0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
c000: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
c010: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
c020: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
c030: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c040: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
c050: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
c060: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
c070: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
c080: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
c090: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
c0a0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
c0b0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
c0c0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
c0d0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
c0e0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
c0f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
c100: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
c110: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
c120: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
c130: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
c140: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
c150: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
c160: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
c170: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
c180: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
c190: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
c1a0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
c1b0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
c1c0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
c1d0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
c1e0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
c1f0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
c200: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
c210: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
c220: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
c230: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
c240: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
c250: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
c260: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
c270: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
c280: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
c290: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
c2a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c2b0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
c2c0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
c2d0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
c2e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c2f0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
c300: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
c310: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
c320: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
c330: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
c340: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
c350: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
c360: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
c370: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c380: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
c390: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
c3a0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
c3b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
c3c0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
c3d0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
c3e0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
c3f0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
c400: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
c410: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
c420: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
c430: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
c440: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
c450: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
c460: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c470: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
c480: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
c490: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
c4a0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
c4b0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
c4c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
c4d0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
c4e0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
c4f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c500: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
c510: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
c520: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
c530: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
c540: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
c550: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
c560: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
c570: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
c580: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
c590: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
c5a0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
c5b0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
c5c0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
c5d0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
c5e0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
c5f0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
c600: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
c610: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
c620: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
c630: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
c640: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
c650: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
c660: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
c670: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c680: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c690: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
c6a0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
c6b0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
c6c0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
c6d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c6e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c6f0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
c700: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
c710: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
c720: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c730: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
c740: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
c750: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
c760: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
c770: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
c780: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
c790: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c7a0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
c7b0: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
c7c0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
c7d0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
c7e0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
c7f0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
c800: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
c810: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
c820: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
c830: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
c840: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
c850: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
c860: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
c870: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
c880: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
c890: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
c8a0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
c8b0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
c8c0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
c8d0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
c8e0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
c8f0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
c900: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
c910: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
c920: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
c930: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
c940: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
c950: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
c960: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c970: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
c980: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
c990: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
c9a0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
c9b0: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
c9c0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
c9d0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
c9e0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
c9f0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ca00: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
ca10: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ca20: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
ca30: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ca40: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
ca50: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
ca60: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
ca70: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
ca80: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
ca90: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
caa0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
cab0: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
cac0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
cad0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
cae0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
caf0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
cb00: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
cb10: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
cb20: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
cb30: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
cb40: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
cb50: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
cb60: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
cb70: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
cb80: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
cb90: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
cba0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
cbb0: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
cbc0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
cbd0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
cbe0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
cbf0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
cc00: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
cc10: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
cc20: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
cc30: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
cc40: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
cc50: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
cc60: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cc70: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cc80: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
cc90: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
cca0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ccb0: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ccc0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ccd0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
cce0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ccf0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
cd00: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
cd10: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
cd20: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
cd30: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
cd40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cd50: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
cd60: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
cd70: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
cd80: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
cd90: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
cda0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
cdb0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
cdc0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
cdd0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
cde0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
cdf0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ce00: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ce10: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ce20: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
ce30: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
ce40: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
ce50: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
ce60: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
ce70: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ce80: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ce90: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
cea0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ceb0: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
cec0: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ced0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
cee0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
cef0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
cf00: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
cf10: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
cf20: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
cf30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
cf40: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
cf50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
cf60: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
cf70: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cf80: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
cf90: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
cfa0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
cfb0: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
cfc0: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
cfd0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
cfe0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
cff0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
d000: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
d010: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
d020: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
d030: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
d040: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
d050: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
d060: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
d070: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
d080: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
d090: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
d0a0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
d0b0: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
d0c0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
d0d0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
d0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
d0f0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
d100: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
d110: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
d120: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
d130: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
d140: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
d150: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
d160: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d170: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
d180: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
d190: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
d1a0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
d1b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d1c0: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
d1d0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
d1e0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
d1f0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
d200: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
d210: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
d220: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
d230: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
d240: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
d250: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
d260: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
d270: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
d280: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
d290: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
d2a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
d2b0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
d2c0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
d2d0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
d2e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d2f0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
d300: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
d310: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
d320: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
d330: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
d340: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
d350: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
d360: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
d370: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
d380: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
d390: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
d3a0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
d3b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d3c0: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
d3d0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
d3e0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
d3f0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
d400: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
d410: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
d420: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
d430: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d440: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d450: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
d460: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d470: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
d480: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d490: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
d4a0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
d4b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
d4c0: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
d4d0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
d4e0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
d4f0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
d500: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d510: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
d520: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
d530: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
d540: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
d550: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
d560: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
d570: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
d580: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
d590: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
d5a0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
d5b0: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
d5c0: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
d5d0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
d5e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d5f0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
d600: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
d610: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
d620: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
d630: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
d640: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
d650: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d660: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
d670: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
d680: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d690: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
d6a0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
d6b0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
d6c0: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
d6d0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
d6e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
d6f0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
d700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d710: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
d720: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
d730: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
d740: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
d750: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
d760: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
d770: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
d780: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
d790: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
d7a0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
d7b0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
d7c0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
d7d0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
d7e0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
d7f0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
d800: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
d810: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
d820: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
d830: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
d840: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
d850: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
d860: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
d870: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
d880: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
d890: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
d8a0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
d8b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d8c0: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
d8d0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
d8e0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
d8f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d900: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
d910: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
d920: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
d930: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
d940: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
d950: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
d960: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
d970: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
d980: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
d990: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
d9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
d9b0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
d9c0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
d9d0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
d9e0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
d9f0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
da00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
da10: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
da20: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
da30: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
da40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
da50: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
da60: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
da70: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
da80: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
da90: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
daa0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
dab0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
dac0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
dad0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
dae0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
daf0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
db00: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
db10: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
db20: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
db30: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
db40: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
db50: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
db60: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
db70: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
db80: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
db90: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
dba0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
dbb0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
dbc0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
dbd0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
dbe0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
dbf0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
dc00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
dc10: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
dc20: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
dc30: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
dc40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
dc50: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
dc60: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
dc70: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
dc80: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
dc90: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
dca0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
dcb0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
dcc0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
dcd0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
dce0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
dcf0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
dd00: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
dd10: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
dd20: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
dd30: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
dd40: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
dd50: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
dd60: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
dd70: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
dd80: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
dd90: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
dda0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
ddb0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
ddc0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
ddd0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
dde0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ddf0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
de00: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
de10: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
de20: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
de30: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
de40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
de50: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
de60: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
de70: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
de80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
de90: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
dea0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
deb0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
dec0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ded0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
dee0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
def0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
df00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
df10: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
df20: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
df30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
df40: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
df50: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
df60: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
df70: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
df80: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
df90: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
dfa0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
dfb0: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
dfc0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
dfd0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
dfe0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
dff0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
e000: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
e010: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
e020: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
e030: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
e040: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
e050: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
e060: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
e070: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
e080: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
e090: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
e0a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
e0b0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
e0c0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
e0d0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
e0e0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
e0f0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
e100: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
e110: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e120: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c  alize(void);.SQL
e130: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
e140: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
e150: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
e160: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
e170: 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  it(void);.SQLITE
e180: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e190: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
e1a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e1b0: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
e1c0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
e1d0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e1e0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
e1f0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
e200: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
e210: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
e220: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
e230: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
e240: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
e250: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
e260: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
e270: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
e280: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
e290: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
e2a0: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
e2b0: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
e2c0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
e2d0: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
e2e0: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
e2f0: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
e300: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
e310: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
e320: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
e330: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
e340: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
e350: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
e360: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e370: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
e380: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
e390: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
e3a0: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
e3b0: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
e3c0: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
e3d0: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
e3e0: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
e3f0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e400: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
e410: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
e420: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
e430: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
e440: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
e450: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
e460: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
e470: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e480: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
e490: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
e4a0: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
e4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e4c0: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e4e0: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
e4f0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
e500: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
e510: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
e520: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
e530: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
e540: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
e550: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
e560: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
e570: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
e580: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
e590: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
e5a0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
e5b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
e5c0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
e5d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e5e0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
e5f0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
e600: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
e610: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
e620: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
e630: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
e640: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
e650: 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
e660: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
e670: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e680: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
e690: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
e6a0: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
e6b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e6c0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e6d0: 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
e6e0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
e6f0: 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
e700: 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
e710: 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
e720: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
e730: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
e740: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
e750: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
e760: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e770: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
e780: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e790: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
e7a0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  onnections.**.**
e7b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
e7c0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e7d0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e7e0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
e7f0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
e800: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e810: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
e820: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
e830: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
e840: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
e850: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
e860: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
e870: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
e880: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
e890: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
e8a0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
e8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
e8c0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
e8d0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e8e0: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
e8f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
e900: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
e910: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
e920: 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
e930: 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
e940: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
e950: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
e960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e970: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
e980: 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
e990: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
e9a0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
e9b0: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
e9c0: 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
e9d0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
e9e0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
e9f0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
ea00: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
ea10: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
ea20: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
ea30: 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
ea40: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  I int sqlite3_db
ea50: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
ea60: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
ea70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea80: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
ea90: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
eaa0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
eab0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
eac0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
ead0: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
eae0: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
eaf0: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
eb00: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
eb10: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
eb20: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
eb30: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
eb40: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
eb50: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
eb60: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
eb70: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
eb80: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
eb90: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
eba0: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
ebb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ebc0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
ebd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
ebe0: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
ebf0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
ec00: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
ec10: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
ec20: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
ec30: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
ec40: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
ec50: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
ec60: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
ec70: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
ec80: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
ec90: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
eca0: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
ecb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ecc0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
ecd0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
ece0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
ecf0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
ed00: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
ed10: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
ed20: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
ed30: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
ed40: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
ed50: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
ed60: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
ed70: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
ed80: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
ed90: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
eda0: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
edb0: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
edc0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
edd0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
ede0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
edf0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
ee00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
ee10: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
ee20: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
ee30: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
ee40: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
ee50: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
ee60: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ee70: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
ee80: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
ee90: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
eea0: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
eeb0: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
eec0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
eed0: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
eee0: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
eef0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
ef00: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
ef10: 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
ef20: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
ef30: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
ef40: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
ef50: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
ef60: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
ef70: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
ef80: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
ef90: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
efa0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
efb0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
efc0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
efd0: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
efe0: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
eff0: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
f000: 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
f010: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
f020: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
f030: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
f040: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
f050: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
f060: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
f070: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
f080: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
f090: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
f0a0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
f0b0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
f0c0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
f0d0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
f0e0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
f0f0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
f100: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
f110: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
f120: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f130: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
f140: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
f150: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
f160: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
f170: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
f180: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
f190: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
f1a0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
f1b0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
f1c0: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
f1d0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
f1e0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
f1f0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
f200: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f210: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
f220: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
f230: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
f240: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
f250: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
f260: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
f270: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
f280: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
f290: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
f2a0: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
f2b0: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
f2c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
f2d0: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
f2e0: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
f2f0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
f300: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
f310: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
f320: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
f330: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
f340: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
f350: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
f360: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
f370: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
f380: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
f390: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
f3a0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
f3b0: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
f3c0: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
f3d0: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
f3e0: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
f3f0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
f400: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
f410: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
f420: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
f430: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
f440: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
f450: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
f460: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
f470: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
f480: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
f490: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
f4a0: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
f4b0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
f4c0: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
f4d0: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
f4e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
f4f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
f500: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
f510: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
f520: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
f530: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
f540: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
f550: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
f560: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
f570: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
f580: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
f590: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
f5a0: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
f5b0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
f5c0: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
f5d0: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
f5e0: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
f5f0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
f600: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
f610: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
f620: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
f630: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
f640: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
f650: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
f660: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
f670: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
f680: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
f690: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
f6a0: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
f6b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
f6c0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
f6d0: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
f6e0: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
f6f0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
f700: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
f710: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
f720: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f730: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
f740: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
f750: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
f760: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
f770: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
f780: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
f790: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
f7a0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
f7b0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
f7c0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
f7d0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
f7e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
f7f0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
f800: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
f810: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
f820: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
f830: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
f840: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
f850: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
f860: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
f870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
f880: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
f890: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
f8a0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
f8b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
f8c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
f8d0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
f8e0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
f8f0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
f900: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
f910: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
f920: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
f930: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
f940: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f950: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
f960: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
f970: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
f980: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
f990: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
f9a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f9b0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
f9c0: 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
f9d0: 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
f9e0: 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
f9f0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
fa00: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
fa10: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
fa20: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fa30: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
fa40: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
fa50: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
fa60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
fa70: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
fa80: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
fa90: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
faa0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
fab0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
fac0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
fad0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
fae0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
faf0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
fb00: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
fb10: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
fb20: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
fb30: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
fb40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
fb50: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
fb60: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
fb70: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
fb80: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
fb90: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
fba0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
fbb0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
fbc0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
fbd0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
fbe0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fbf0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
fc00: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
fc10: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
fc20: 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
fc30: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc40: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
fc50: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
fc60: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
fc70: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
fc80: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
fc90: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
fca0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
fcb0: 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
fcc0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
fcd0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
fce0: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
fcf0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
fd00: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
fd10: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
fd20: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
fd30: 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
fd40: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fd50: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
fd60: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
fd70: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
fd80: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
fd90: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
fda0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
fdb0: 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
fdc0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
fdd0: 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
fde0: 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
fdf0: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
fe00: 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
fe10: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
fe20: 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
fe30: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
fe40: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
fe50: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fe60: 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
fe70: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
fe80: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
fe90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
fea0: 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
feb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
fec0: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fed0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fee0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fef0: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
ff00: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
ff10: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
ff20: 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
ff30: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
ff40: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ff50: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
ff60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ff70: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
ff80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
ff90: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
ffa0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
ffb0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
ffc0: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
ffd0: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
ffe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
fff0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
10000 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
10010 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
10020 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
10030 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
10040 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
10050 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10060 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
10070 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
10080 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
10090 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
100a0 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
100b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
100c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
100d0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
100e0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
100f0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
10100 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
10110 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
10120 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
10130 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
10140 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
10150 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
10160 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
10170 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
10180 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10190 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
101a0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
101b0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
101c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
101d0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
101e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
101f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10200 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
10210 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
10220 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
10230 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
10240 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10250 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10260 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10270 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10280 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10290 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
102a0 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
102b0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
102c0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
102d0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
102e0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
102f0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
10300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10310 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
10320 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
10330 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
10340 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
10350 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
10360 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10370 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
10380 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
10390 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
103a0 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
103b0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
103c0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
103d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
103e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
103f0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
10400 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
10410 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
10420 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
10430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10440 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
10450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10460 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
10470 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
10480 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
10490 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
104a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
104b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
104c0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
104d0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
104e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
104f0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
10500 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
10510 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
10520 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10530 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
10540 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
10550 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10560 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
10570 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
10580 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
10590 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
105a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
105b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
105c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
105d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
105e0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
105f0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10600 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10610 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10620 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10630 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
10640 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10650 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10660 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
10670 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
10680 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
10690 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
106a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
106b0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
106c0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
106d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
106e0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
106f0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
10700 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
10710 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
10720 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
10730 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
10740 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10750 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
10760 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
10770 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
10780 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
10790 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
107a0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
107b0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
107c0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
107d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
107e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
107f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10800 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10810 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10820 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10830 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10840 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
10850 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10860 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
10870 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
10880 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
10890 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
108a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
108b0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
108c0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
108d0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
108e0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
108f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10900 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
10910 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
10920 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
10930 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
10940 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
10950 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
10960 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
10970 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10980 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10990 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
109a0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
109b0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
109c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
109d0 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
109e0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
109f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
10a00 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
10a10 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
10a20 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
10a30 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
10a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
10a50 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
10a60 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10a70 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
10a80 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
10a90 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
10aa0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10ab0 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
10ac0 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
10ad0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
10ae0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
10af0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
10b00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10b10 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
10b20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
10b30 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
10b40 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
10b50 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
10b60 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
10b70 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
10b80 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
10b90 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
10ba0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
10bb0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
10bc0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10bd0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
10be0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
10bf0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
10c00 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10c10 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
10c20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
10c30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10c40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
10c50 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
10c60 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
10c70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
10c80 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
10c90 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
10ca0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
10cb0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
10cc0 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
10cd0 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
10ce0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
10cf0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
10d00 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
10d10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
10d20 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
10d30 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10d40 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
10d50 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
10d60 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
10d70 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
10d80 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
10d90 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
10da0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
10db0 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
10dc0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10dd0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
10de0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
10df0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10e00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
10e10 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
10e20 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
10e30 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
10e40 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
10e50 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
10e60 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
10e70 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
10e80 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
10e90 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
10ea0 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
10eb0 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
10ec0 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
10ed0 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
10ee0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
10ef0 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
10f00 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
10f10 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
10f20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
10f30 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
10f40 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
10f50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
10f60 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
10f70 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
10f80 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
10f90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10fa0 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
10fb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
10fc0 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
10fd0 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
10fe0 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
10ff0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11000 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
11010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11020 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
11030 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
11040 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
11050 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
11060 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
11070 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
11080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
11090 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
110a0 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
110b0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
110c0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
110d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
110e0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
110f0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
11100 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
11110 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
11120 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
11130 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
11140 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
11150 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
11160 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
11170 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11180 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
11190 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
111a0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
111b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
111c0 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
111d0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
111e0 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
111f0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
11200 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
11210 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
11220 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
11230 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
11240 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
11250 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
11260 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
11270 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
11280 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
11290 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
112a0 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
112b0 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
112c0 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
112d0 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
112e0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
112f0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
11300 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
11310 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
11320 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
11330 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
11340 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
11350 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
11360 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11370 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
11380 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
11390 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
113a0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
113b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
113c0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
113d0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
113e0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
113f0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
11400 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
11410 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
11420 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
11430 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
11440 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
11450 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
11460 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
11470 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
11480 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
11490 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
114a0 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
114b0 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
114c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
114d0 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
114e0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
114f0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
11500 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
11510 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
11520 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
11530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
11550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11560 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
11570 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11580 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11590 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
115a0 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
115b0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
115c0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
115d0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
115e0 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
115f0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
11600 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11620 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
11630 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11640 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
11650 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
11660 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
11670 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
11680 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
11690 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
116a0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
116b0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
116c0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
116d0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
116e0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
116f0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
11700 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
11710 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
11720 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
11730 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
11740 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
11750 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
11760 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
11770 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
11780 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
11790 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
117a0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
117b0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
117c0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
117d0 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
117e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
117f0 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
11800 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
11810 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
11820 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
11830 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
11840 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
11850 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
11860 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
11870 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11880 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
11890 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
118a0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
118b0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
118c0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
118d0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
118e0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
118f0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
11900 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
11910 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
11920 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
11930 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
11940 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
11950 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
11960 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
11970 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
11980 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
11990 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
119a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
119b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
119c0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
119d0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
119e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
119f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11a00 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11a10 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11a20 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11a30 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
11a40 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11a50 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
11a60 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
11a70 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
11a80 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
11a90 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
11aa0 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
11ab0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
11ac0 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
11ad0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
11ae0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
11af0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
11b00 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
11b10 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
11b20 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
11b30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11b40 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
11b50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11b60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11b70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11b80 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11b90 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11ba0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11bb0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
11bc0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
11bd0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
11be0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
11bf0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
11c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11c10 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
11c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
11c30 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
11c40 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
11c50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11c60 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
11c70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11c80 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
11c90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11ca0 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
11cb0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11cc0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11cd0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11ce0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11cf0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11d00 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11d10 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
11d20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
11d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
11d40 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
11d50 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
11d60 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
11d70 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
11d80 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
11d90 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
11da0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
11db0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
11dc0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
11dd0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
11de0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
11df0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
11e00 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
11e10 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
11e20 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
11e30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
11e40 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11e50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11e60 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11e70 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11e80 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11e90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11ea0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
11eb0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
11ec0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
11ed0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
11ee0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
11ef0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11f00 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
11f10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11f20 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
11f30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
11f40 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
11f50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
11f60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11f70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
11f80 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
11f90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11fa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11fb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11fc0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
11fd0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
11fe0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
11ff0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12000 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
12010 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12020 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
12030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12040 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
12050 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
12060 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
12070 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
12080 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
12090 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
120a0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
120b0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
120c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
120d0 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
120e0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
120f0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
12100 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
12110 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
12120 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12130 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
12140 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12150 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
12160 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
12170 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
12180 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
12190 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
121a0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
121b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
121c0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
121d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
121e0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
121f0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12200 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12210 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12220 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
12230 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
12240 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
12250 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
12260 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
12270 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
12280 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
12290 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
122a0 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
122b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
122c0 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
122d0 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
122e0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
122f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
12300 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12310 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12320 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
12330 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12340 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
12350 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12360 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12370 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12380 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12390 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
123a0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
123b0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
123c0 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
123d0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
123e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
123f0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
12400 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
12410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
12420 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
12430 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
12440 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12450 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
12460 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
12470 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
12480 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
12490 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
124a0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
124b0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
124c0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
124d0 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
124e0 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
124f0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
12500 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
12510 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
12520 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
12530 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
12540 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
12550 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
12560 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
12570 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
12580 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
12590 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
125a0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
125b0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
125c0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
125d0 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
125e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
125f0 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
12600 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
12610 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12620 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
12630 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
12640 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
12650 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
12660 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
12670 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12680 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
12690 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
126a0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
126b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
126c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
126d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
126e0 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
126f0 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
12700 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
12710 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
12720 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
12730 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
12740 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
12750 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
12760 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
12770 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
12780 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
12790 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
127a0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
127b0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
127c0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
127d0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
127e0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
127f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
12800 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
12810 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12820 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
12830 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
12840 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
12850 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
12860 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
12870 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
12880 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
12890 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
128a0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
128b0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
128c0 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
128d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
128e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
128f0 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
12900 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
12910 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12920 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
12930 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
12940 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
12950 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
12960 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
12970 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69  d. If URI handli
12980 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
12990 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
129a0 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20  names.** passed 
129b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
129c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
129d0 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  en_v2()], [sqlit
129e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
129f0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
12a00 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
12a10 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
12a20 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
12a30 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
12a40 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
12a50 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
12a60 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
12a70 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
12a80 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
12a90 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
12aa0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
12ab0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
12ac0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
12ad0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
12ae0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
12af0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
12b00 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
12b10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
12b20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
12b30 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  ed. By default, 
12b40 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12b50 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
12b60 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
12b70 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
12b80 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
12b90 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
12ba0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
12bb0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
12bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12bd0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
12be0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12bf0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
12c00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12c10 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
12c20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
12c30 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
12c40 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
12c50 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
12c60 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
12c70 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
12c80 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
12c90 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
12ca0 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
12cb0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
12cc0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
12cd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12ce0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
12cf0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
12d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12d10 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
12d20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
12d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12d40 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
12d50 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
12d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12d70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
12d80 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
12d90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
12da0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12db0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12dc0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
12dd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
12de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12df0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12e00 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
12e10 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
12e20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
12e30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12e40 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
12e50 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
12e60 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
12e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12e80 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
12e90 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
12ea0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
12eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12ec0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
12ed0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
12ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12ef0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
12f00 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
12f10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12f20 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
12f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12f40 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
12f50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
12f60 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
12f70 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
12f80 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
12f90 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
12fa0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
12fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12fc0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
12fd0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
12fe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12ff0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
13000 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
13010 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
13020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13030 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
13040 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13060 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
13070 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
13080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13090 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
130a0 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
130b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
130c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
130d0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
130e0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
130f0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
13100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13110 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
13120 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
13130 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
13140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13150 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
13160 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
13170 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
13180 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
13190 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
131a0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
131b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
131c0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
131d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
131e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
131f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
13200 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13210 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13220 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13230 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13240 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13250 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13260 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13270 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13280 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
13290 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
132a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
132b0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
132c0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
132d0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
132e0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
132f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13300 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
13310 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13320 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
13330 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
13340 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
13350 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
13360 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
13370 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
13380 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
13390 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
133a0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
133b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
133c0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
133d0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
133e0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
133f0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
13400 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
13410 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
13420 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
13430 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
13440 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
13450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13460 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
13470 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
13480 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
13490 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
134a0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
134b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
134c0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
134d0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
134e0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
134f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
13500 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
13510 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
13520 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
13530 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
13540 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
13550 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
13560 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
13570 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
13580 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13590 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
135a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
135b0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
135c0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
135d0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
135e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
135f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
13600 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
13610 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
13620 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13630 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
13640 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
13650 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
13660 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
13670 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
13680 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
13690 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
136a0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
136b0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
136c0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
136d0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
136e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
136f0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
13700 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
13710 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
13720 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
13730 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
13740 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
13750 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
13760 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
13770 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
13780 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13790 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
137a0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
137b0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
137c0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
137d0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
137e0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
137f0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
13800 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
13810 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
13820 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
13830 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
13840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13850 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
13860 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
13870 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
13880 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13890 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
138a0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
138b0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
138c0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
138d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
138e0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
138f0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
13900 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
13910 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13920 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
13930 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
13940 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
13950 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
13960 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
13970 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
13980 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
13990 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
139a0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
139b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
139c0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
139d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
139e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
139f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
13a00 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
13a10 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
13a20 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
13a30 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
13a40 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
13a50 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
13a60 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
13a70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
13a80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13a90 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
13aa0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
13ab0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
13ac0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
13ad0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
13ae0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
13af0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
13b00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13b10 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
13b20 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
13b30 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
13b40 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
13b50 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13b60 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13b70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13b80 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
13b90 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
13ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
13bb0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
13bc0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
13bd0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
13be0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
13bf0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
13c00 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
13c10 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
13c20 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13c30 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
13c40 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
13c50 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
13c60 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
13c70 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
13c80 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
13c90 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
13ca0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
13cb0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13cc0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13cd0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
13ce0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
13cf0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
13d00 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
13d10 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
13d20 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
13d30 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
13d40 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
13d50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13d60 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
13d70 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
13d80 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
13d90 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
13da0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
13db0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
13dc0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
13dd0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
13de0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
13df0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
13e00 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
13e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
13e20 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
13e30 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
13e40 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
13e50 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13e60 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
13e70 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
13e80 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
13e90 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
13ea0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
13eb0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
13ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
13ed0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
13ee0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
13ef0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
13f00 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
13f10 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13f20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
13f30 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
13f40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
13f50 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
13f60 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
13f70 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
13f80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
13f90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13fa0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
13fb0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
13fc0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
13fd0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
13fe0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
13ff0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
14000 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
14010 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
14020 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
14030 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
14040 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
14050 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
14060 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
14070 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
14080 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
14090 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
140a0 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
140b0 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
140c0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
140d0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
140e0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
140f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
14100 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
14110 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
14120 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
14130 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
14140 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
14150 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
14160 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
14170 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
14180 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
14190 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
141a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
141b0 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
141c0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
141d0 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
141e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
141f0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
14200 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14210 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
14220 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
14230 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
14240 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
14250 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
14260 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
14270 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
14280 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
14290 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
142a0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
142b0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
142c0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
142d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
142e0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
142f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
14300 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
14310 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
14320 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
14330 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
14340 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
14350 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
14360 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
14370 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
14380 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
14390 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
143a0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
143b0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
143c0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
143d0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
143e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
143f0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
14400 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
14410 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
14420 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
14430 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
14440 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
14450 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
14460 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
14470 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
14480 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
14490 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
144a0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
144b0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
144c0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
144d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
144e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
144f0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
14500 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
14510 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
14520 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
14530 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
14540 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
14550 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
14560 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
14570 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
14580 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
14590 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
145a0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
145b0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
145c0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
145d0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
145e0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
145f0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
14600 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
14610 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
14620 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
14630 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
14640 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
14650 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
14660 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
14670 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
14680 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
14690 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
146a0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
146b0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
146c0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
146d0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
146e0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
146f0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
14700 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
14710 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
14720 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
14730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
14740 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
14750 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
14760 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
14770 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
14780 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
14790 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
147a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
147b0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
147c0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
147d0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
147e0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
147f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
14800 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
14810 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
14820 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
14830 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
14840 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
14850 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
14860 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
14870 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
14880 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
14890 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
148a0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
148b0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
148c0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
148d0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
148e0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
148f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
14900 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
14910 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
14920 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
14930 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
14940 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
14950 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
14960 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
14970 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
14980 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
14990 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
149a0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
149b0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
149c0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
149d0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
149e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
149f0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
14a00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
14a10 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
14a20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
14a30 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
14a40 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
14a50 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
14a60 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
14a70 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
14a80 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
14a90 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
14aa0 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
14ab0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
14ac0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
14ad0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14ae0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
14af0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
14b00 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
14b10 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
14b20 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
14b30 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
14b40 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
14b50 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
14b60 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
14b70 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
14b80 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
14b90 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
14ba0 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
14bb0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
14bc0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
14bd0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
14be0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
14bf0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
14c00 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
14c10 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
14c20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
14c30 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
14c40 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
14c50 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
14c60 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
14c70 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
14c80 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
14c90 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
14ca0 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
14cb0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
14cc0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
14cd0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
14ce0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
14cf0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
14d00 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
14d10 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
14d20 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
14d30 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
14d40 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
14d50 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
14d60 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
14d70 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
14d80 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
14d90 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
14da0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
14db0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
14dc0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
14dd0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
14de0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
14df0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
14e00 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
14e10 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
14e20 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
14e30 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
14e40 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
14e50 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
14e60 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
14e70 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
14e80 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
14e90 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
14ea0 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
14eb0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
14ec0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
14ed0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
14ee0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
14ef0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14f00 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
14f10 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
14f20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
14f30 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
14f40 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14f50 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
14f60 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
14f70 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
14f80 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
14f90 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
14fa0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
14fb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
14fc0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
14fd0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
14fe0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
14ff0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
15000 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
15010 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
15020 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
15030 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
15040 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
15050 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
15060 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
15070 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
15080 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
15090 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
150a0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
150b0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
150c0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
150d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
150e0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
150f0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
15100 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15110 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
15120 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15130 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
15140 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
15150 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
15160 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
15170 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
15180 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
15190 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
151a0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
151b0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
151c0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
151d0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
151e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
151f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
15200 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
15210 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
15220 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
15230 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
15240 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
15250 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15260 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15270 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
15280 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
15290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
152a0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
152b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
152c0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
152d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
152e0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
152f0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
15300 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
15310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
15320 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
15330 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15340 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
15350 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15360 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15370 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15380 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15390 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
153a0 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
153b0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
153c0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
153d0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
153e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
153f0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
15400 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
15410 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15420 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
15430 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
15440 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
15450 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
15460 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
15470 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
15480 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
15490 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
154a0 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
154b0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
154c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
154d0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
154e0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
154f0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
15500 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
15510 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
15520 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
15530 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
15540 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
15550 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
15560 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
15570 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
15580 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
15590 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
155a0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
155b0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
155c0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
155d0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
155e0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
155f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
15600 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
15610 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
15620 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
15630 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
15640 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
15650 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
15660 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
15670 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
15680 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
15690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
156a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
156b0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
156c0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
156d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
156e0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
156f0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
15700 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
15710 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
15720 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
15730 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
15740 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
15750 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
15760 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
15770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15780 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
15790 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
157a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
157b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
157c0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
157d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
157e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
157f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
15800 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15810 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
15820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
15830 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
15840 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
15850 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
15860 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
15870 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
15880 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
15890 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
158a0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
158b0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
158c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
158d0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
158e0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
158f0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
15900 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
15910 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
15920 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
15930 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
15940 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
15950 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
15960 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
15970 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
15980 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
15990 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
159a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
159b0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
159c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
159d0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
159e0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
159f0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
15a00 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
15a10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
15a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15a30 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
15a40 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
15a50 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
15a60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15a70 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
15a80 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
15a90 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
15aa0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
15ab0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
15ac0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
15ad0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
15ae0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
15af0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
15b00 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
15b10 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
15b20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
15b30 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
15b40 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
15b50 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
15b60 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
15b70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
15b80 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
15b90 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
15ba0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
15bb0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
15bc0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
15bd0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
15be0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
15bf0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
15c00 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
15c10 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
15c20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
15c30 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
15c40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
15c50 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
15c60 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
15c70 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
15c80 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
15c90 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
15ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15cb0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
15cc0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
15cd0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15ce0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15cf0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
15d00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
15d10 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
15d20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
15d30 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
15d40 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
15d50 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
15d60 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
15d70 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
15d80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15d90 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
15da0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15db0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
15dc0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
15dd0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
15de0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
15df0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
15e00 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
15e10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15e20 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
15e30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15e40 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
15e50 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
15e60 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
15e70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
15e80 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
15e90 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
15ea0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15eb0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15ec0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
15ed0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
15ee0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
15ef0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
15f10 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
15f20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
15f30 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
15f40 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
15f50 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
15f60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15f70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
15f80 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
15f90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15fa0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
15fb0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
15fc0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
15fd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15fe0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
15ff0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
16000 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
16010 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
16020 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
16030 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
16040 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
16050 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
16060 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
16070 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
16080 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
16090 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
160a0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
160b0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
160c0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
160d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
160e0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
160f0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
16100 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
16110 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
16120 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
16130 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
16140 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
16150 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
16160 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
16170 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
16180 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
16190 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
161a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
161b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
161c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
161d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
161e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
161f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
16200 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
16210 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
16220 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
16230 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
16240 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
16250 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
16260 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
16270 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
16280 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
16290 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
162a0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
162b0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
162c0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
162d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
162e0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
162f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
16300 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
16310 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
16320 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
16330 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
16340 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
16350 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
16360 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
16370 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
16380 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
16390 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
163a0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
163b0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
163c0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
163d0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
163e0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
163f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
16400 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
16410 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
16420 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
16430 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
16440 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
16450 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
16460 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
16470 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
16480 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
16490 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
164a0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
164b0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
164c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
164d0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
164e0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
164f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
16500 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
16510 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
16520 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
16530 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
16540 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
16550 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
16560 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
16570 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
16580 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
16590 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
165a0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
165b0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
165c0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
165d0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
165e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
165f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
16600 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
16610 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
16620 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
16630 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
16640 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
16650 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
16660 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
16670 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
16680 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
16690 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
166a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
166b0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
166c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
166d0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
166e0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
166f0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
16700 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
16710 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
16720 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
16730 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
16740 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
16750 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
16760 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
16770 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
16780 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
16790 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
167a0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
167b0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
167c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
167d0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
167e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
167f0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
16800 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
16810 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
16820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16830 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
16840 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
16850 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
16860 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
16870 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16880 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
16890 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
168a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
168b0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
168c0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
168d0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
168e0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
168f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
16900 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
16910 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
16920 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
16930 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
16940 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
16950 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
16960 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
16970 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
16980 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
16990 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
169a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
169b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
169c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
169d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
169e0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
169f0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
16a00 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
16a10 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
16a20 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
16a30 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
16a40 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
16a50 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
16a60 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
16a70 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
16a80 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
16a90 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
16aa0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
16ab0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
16ac0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
16ad0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
16ae0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
16af0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
16b00 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
16b10 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
16b20 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
16b30 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
16b40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16b50 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
16b60 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
16b70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
16b80 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
16b90 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
16ba0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
16bb0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
16bc0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
16bd0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
16be0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
16bf0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
16c00 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
16c10 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
16c20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
16c30 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
16c40 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
16c50 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
16c60 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
16c70 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
16c80 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
16c90 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
16ca0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
16cb0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
16cc0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
16cd0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
16ce0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
16cf0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
16d00 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
16d10 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
16d20 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
16d30 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
16d40 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
16d50 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
16d60 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
16d70 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
16d80 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
16d90 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
16da0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
16db0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
16dc0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
16dd0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
16de0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
16df0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
16e00 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
16e10 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
16e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
16e30 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
16e40 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
16e50 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16e60 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
16e70 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
16e80 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
16e90 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
16ea0 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
16eb0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
16ec0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
16ed0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
16ee0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
16ef0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
16f00 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
16f10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
16f20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
16f30 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
16f40 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
16f50 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
16f60 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
16f70 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
16f80 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
16f90 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
16fa0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
16fb0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
16fc0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
16fd0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
16fe0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
16ff0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
17000 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
17010 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
17020 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
17030 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
17040 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
17050 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
17060 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
17070 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
17080 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
17090 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
170a0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
170b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
170c0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
170d0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
170e0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
170f0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
17100 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
17110 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
17120 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
17130 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
17140 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
17150 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
17160 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
17170 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
17180 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
17190 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
171a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
171b0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
171c0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
171d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
171e0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
171f0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
17200 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
17210 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
17220 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
17230 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
17240 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
17250 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
17260 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
17270 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
17280 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
17290 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
172a0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
172b0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
172c0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
172d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
172e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
172f0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
17300 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
17310 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
17320 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
17330 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
17340 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
17350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
17370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17380 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
17390 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
173a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
173b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
173c0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
173d0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
173e0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
173f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
17400 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
17410 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
17420 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
17430 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17440 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
17450 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
17460 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
17470 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
17480 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
17490 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
174a0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
174b0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
174c0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
174d0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
174e0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
174f0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
17500 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
17510 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
17520 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
17530 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
17540 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
17550 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
17560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
17570 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
17580 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
17590 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
175a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
175b0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
175c0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
175d0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
175e0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
175f0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
17600 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
17610 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
17620 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
17630 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
17640 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17660 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
17670 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
17680 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
17690 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
176a0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
176b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
176c0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
176d0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
176e0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
176f0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
17700 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
17710 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
17720 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
17730 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
17740 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
17750 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
17760 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
17770 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
17780 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
17790 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
177a0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
177b0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
177c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
177d0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
177e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
177f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
17800 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
17810 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
17820 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
17830 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
17840 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
17850 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
17860 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
17870 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
17880 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
17890 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
178a0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
178b0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
178c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
178d0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
178e0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
178f0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
17900 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
17910 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
17920 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
17930 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
17940 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
17950 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
17960 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
17970 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
17980 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
17990 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
179a0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
179b0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
179c0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
179d0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
179e0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
179f0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
17a00 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
17a10 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
17a20 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
17a30 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
17a40 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
17a50 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
17a60 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
17a70 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
17a80 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
17a90 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
17aa0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
17ab0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
17ac0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
17ad0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
17ae0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
17af0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
17b00 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
17b10 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
17b20 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
17b30 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
17b40 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
17b50 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
17b60 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17b70 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
17b80 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
17b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
17ba0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
17bb0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
17bc0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
17bd0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
17be0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
17bf0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
17c00 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
17c10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17c20 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
17c30 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
17c40 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
17c50 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
17c60 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
17c70 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
17c80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
17c90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17ca0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
17cb0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
17cc0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
17cd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
17ce0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
17cf0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
17d00 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
17d10 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
17d20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
17d30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
17d40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
17d50 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
17d60 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
17d70 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
17d80 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
17d90 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
17da0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
17db0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
17dc0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
17dd0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
17de0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
17df0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
17e00 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
17e10 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17e20 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17e30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
17e40 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
17e50 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17e60 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
17e70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17e80 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
17e90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
17ea0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
17eb0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
17ec0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
17ed0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
17ee0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17ef0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
17f00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17f10 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
17f20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17f30 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
17f40 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17f50 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
17f60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
17f70 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
17f80 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
17f90 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
17fa0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
17fb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
17fc0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
17fd0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
17fe0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
17ff0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
18000 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
18010 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
18020 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
18030 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
18040 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
18050 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
18060 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
18070 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
18080 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
18090 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
180a0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
180b0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
180c0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
180d0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
180e0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
180f0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
18100 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
18110 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
18120 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18130 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
18140 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
18150 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
18160 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
18170 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
18180 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
18190 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
181a0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
181b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
181c0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
181d0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
181e0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
181f0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
18200 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
18210 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
18220 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
18230 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
18240 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
18250 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
18260 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18270 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
18280 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
18290 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
182a0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
182b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
182c0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
182d0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
182e0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
182f0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
18300 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
18310 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
18320 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
18330 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
18340 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
18350 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
18360 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
18370 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
18380 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
18390 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
183a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
183b0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
183c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
183d0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
183e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
183f0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
18400 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
18410 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
18420 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
18430 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
18440 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
18450 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
18460 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
18470 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
18480 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
18490 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
184a0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
184b0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
184c0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
184d0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
184e0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
184f0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
18500 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
18510 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
18520 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
18530 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
18540 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18550 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
18560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18570 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
18580 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
18590 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
185a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
185b0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
185c0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
185d0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
185e0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
185f0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
18600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18610 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
18620 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
18630 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
18640 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
18650 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
18660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
18670 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18680 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
18690 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
186a0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
186b0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
186c0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
186d0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
186e0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
186f0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
18700 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
18710 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
18720 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
18730 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
18740 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
18750 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
18760 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
18770 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
18780 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
18790 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
187a0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
187b0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
187c0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
187d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
187e0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
187f0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
18800 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
18810 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
18820 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
18830 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
18840 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
18850 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
18860 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
18870 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
18880 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
18890 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
188a0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
188b0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
188c0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
188d0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
188e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
188f0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
18900 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
18910 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
18920 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
18930 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
18940 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
18950 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
18960 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
18970 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
18980 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
18990 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
189a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
189b0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
189c0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
189d0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
189e0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
189f0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
18a00 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
18a10 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18a20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
18a30 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
18a40 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
18a50 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
18a60 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
18a70 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
18a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
18a90 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
18aa0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
18ab0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18ac0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18ad0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18ae0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18af0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18b00 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
18b10 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
18b20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18b30 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
18b40 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
18b50 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
18b60 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
18b70 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
18b80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18b90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18ba0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
18bb0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18bc0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18bd0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18be0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18bf0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18c00 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18c10 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18c20 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18c30 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18c40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18c50 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18c60 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18c70 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18c80 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18c90 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18ca0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18cb0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18cc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18cd0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18ce0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18cf0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18d00 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18d10 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18d20 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18d30 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18d40 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18d50 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18d60 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18d70 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18d80 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18d90 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18da0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18db0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18dc0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18dd0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18de0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18df0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18e00 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18e10 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18e20 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18e30 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18e40 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18e50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18e60 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18e70 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18e80 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18e90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18ea0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18eb0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18ec0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18ed0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18ee0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18ef0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18f00 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18f10 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18f20 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18f30 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18f40 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18f50 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18f60 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18f70 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18f80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18f90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18fa0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18fb0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18fc0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18fd0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18fe0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18ff0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
19000 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
19010 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19020 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
19030 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
19040 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
19050 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
19060 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
19070 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
19080 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
19090 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
190a0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
190b0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
190c0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
190d0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
190e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
190f0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
19100 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
19110 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
19120 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
19130 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19140 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
19150 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
19160 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
19170 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
19180 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
19190 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
191a0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
191b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
191c0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
191d0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
191e0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
191f0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
19200 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
19210 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
19220 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
19230 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
19240 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
19250 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
19260 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
19270 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
19280 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
19290 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
192a0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
192b0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
192c0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
192d0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
192e0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
192f0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
19300 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19310 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
19320 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
19330 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
19340 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
19350 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
19360 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
19370 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
19380 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
19390 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
193a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
193b0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
193c0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
193d0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
193e0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
193f0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
19400 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
19410 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
19420 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
19430 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
19440 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
19450 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
19460 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
19470 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
19480 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
19490 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
194a0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
194b0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
194c0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
194d0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
194e0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  tring.)^.*/.SQLI
194f0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
19500 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
19510 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53  st char*,...);.S
19520 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
19530 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
19540 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
19550 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
19560 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
19570 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
19580 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
19590 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
195a0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
195b0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
195c0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
195d0 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
195e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
195f0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
19600 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
19610 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
19620 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
19630 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
19640 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
19650 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
19660 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
19670 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
19680 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
19690 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
196a0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
196b0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
196c0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
196d0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
196e0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
196f0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
19700 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
19710 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
19720 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
19730 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
19740 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
19750 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
19760 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
19770 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
19780 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
19790 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
197a0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
197b0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
197c0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
197d0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
197e0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
197f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19800 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
19810 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
19820 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
19830 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
19840 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
19850 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
19860 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
19870 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19880 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
19890 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
198a0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
198b0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
198c0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
198d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
198e0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
198f0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
19900 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
19910 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
19920 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
19930 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
19940 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
19950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19960 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
19970 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
19980 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
19990 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
199a0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
199b0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
199c0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
199d0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
199e0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
199f0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
19a00 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
19a10 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
19a20 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
19a30 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
19a40 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
19a50 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
19a60 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
19a70 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
19a80 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
19a90 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
19aa0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
19ab0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
19ac0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
19ad0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
19ae0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
19af0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
19b00 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
19b10 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
19b20 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
19b30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
19b40 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
19b50 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
19b60 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
19b70 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
19b80 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
19b90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
19ba0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
19bb0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
19bc0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
19bd0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
19be0 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
19bf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19c00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
19c10 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
19c20 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
19c30 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
19c40 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
19c50 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
19c60 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
19c70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19c80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
19c90 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
19ca0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19cb0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
19cc0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
19cd0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
19ce0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
19cf0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
19d00 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
19d10 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
19d20 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
19d30 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
19d40 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19d50 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
19d60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19d70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19d80 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
19d90 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
19da0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
19db0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
19dc0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
19dd0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
19de0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
19df0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
19e00 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19e10 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
19e20 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
19e30 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19e40 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
19e50 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
19e60 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
19e70 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
19e80 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
19e90 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19ea0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
19eb0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
19ec0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
19ed0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
19ee0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
19ef0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
19f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
19f10 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
19f20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
19f40 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
19f50 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
19f60 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
19f70 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
19f80 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
19f90 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
19fa0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
19fb0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
19fc0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
19fd0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
19fe0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
19ff0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1a000 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1a010 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1a020 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1a030 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1a040 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1a050 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1a060 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1a070 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1a080 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1a090 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1a0a0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1a0b0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1a0c0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1a0d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1a0e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1a0f0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1a100 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1a110 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1a120 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1a130 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1a140 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1a150 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1a160 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1a170 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1a180 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1a190 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1a1a0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1a1b0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1a1c0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1a1d0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1a1e0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1a1f0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1a200 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1a210 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1a220 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1a230 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1a240 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1a250 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1a260 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1a270 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1a280 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1a290 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1a2a0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1a2b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a2c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a2d0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1a2e0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1a2f0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1a300 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1a310 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1a320 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1a330 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1a340 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1a350 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1a360 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1a370 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1a380 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1a390 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1a3a0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1a3b0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1a3c0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1a3d0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1a3e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1a3f0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1a400 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1a410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1a420 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1a430 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1a440 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1a450 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1a460 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1a470 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1a480 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1a490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1a4a0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1a4b0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1a4c0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1a4d0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1a4e0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1a4f0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1a500 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1a510 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1a520 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1a530 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a540 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1a550 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1a560 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1a570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1a580 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1a590 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a5a0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1a5b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1a5c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1a5d0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1a5e0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1a5f0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1a600 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1a610 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1a620 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a630 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1a640 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1a650 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1a660 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a670 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1a680 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1a690 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1a6a0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1a6b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a6c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a6d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1a6e0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a6f0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1a700 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1a710 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1a720 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1a730 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a740 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1a750 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1a760 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1a770 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1a780 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1a790 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1a7a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1a7b0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1a7c0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1a7d0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1a7e0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1a7f0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1a800 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1a810 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1a820 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1a830 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1a840 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a850 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1a860 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1a870 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1a880 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1a890 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1a8a0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1a8b0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1a8c0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
1a8d0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1a8e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1a8f0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
1a900 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1a910 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1a920 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1a930 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1a940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1a950 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1a960 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1a970 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1a980 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1a990 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1a9a0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1a9b0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1a9c0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1a9d0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1a9e0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1a9f0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1aa00 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1aa10 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1aa20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1aa30 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1aa40 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1aa50 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1aa60 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1aa70 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1aa80 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1aa90 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1aaa0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1aab0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1aac0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1aad0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1aae0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1aaf0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1ab00 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1ab10 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1ab20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1ab30 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ab40 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
1ab50 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
1ab60 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
1ab70 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
1ab80 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
1ab90 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1aba0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1abb0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
1abc0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1abd0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1abe0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1abf0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
1ac00 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
1ac10 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
1ac20 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1ac30 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1ac40 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1ac50 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1ac60 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1ac70 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1ac80 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1ac90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1aca0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1acb0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1acc0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1acd0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1ace0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1acf0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1ad00 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1ad10 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1ad20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ad30 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1ad40 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1ad50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1ad60 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1ad70 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1ad80 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1ad90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ada0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1adb0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1adc0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1add0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ade0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1adf0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1ae00 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1ae10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ae20 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1ae30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ae40 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1ae50 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1ae60 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1ae70 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1ae80 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1ae90 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1aea0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1aeb0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1aec0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1aed0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1aee0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1aef0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1af00 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1af10 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1af20 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1af30 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1af40 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1af50 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1af60 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1af70 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1af80 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1af90 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1afa0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1afb0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1afc0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1afd0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1afe0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1aff0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1b000 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1b010 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b020 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b030 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1b040 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1b050 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1b060 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1b070 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1b080 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1b090 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1b0a0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1b0b0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1b0c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1b0d0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1b0e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1b0f0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1b100 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b110 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1b120 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1b130 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1b140 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1b150 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b160 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1b170 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1b180 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b190 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1b1a0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1b1b0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1b1c0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1b1d0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1b1e0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1b1f0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1b200 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1b210 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1b220 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1b230 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b240 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1b250 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1b260 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1b270 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1b280 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1b290 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1b2a0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1b2b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1b2c0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1b2d0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1b2e0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1b2f0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1b300 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1b310 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1b320 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1b330 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1b340 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1b350 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1b360 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1b370 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1b380 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1b390 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1b3a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1b3b0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1b3c0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1b3d0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1b3e0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1b3f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1b400 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1b410 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1b420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1b430 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1b440 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1b450 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1b460 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1b470 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1b480 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1b490 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1b4a0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1b4b0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1b4c0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1b4d0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1b4e0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1b4f0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1b500 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1b510 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1b520 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1b530 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1b540 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1b550 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1b560 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1b570 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1b580 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1b590 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1b5a0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1b5b0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1b5c0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1b5d0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1b5e0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1b5f0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1b600 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1b610 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1b620 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1b630 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1b640 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1b650 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1b660 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1b670 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1b680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1b690 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1b6a0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1b6b0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1b6c0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1b6d0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1b6e0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1b6f0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1b700 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1b710 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1b720 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1b730 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1b740 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1b750 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1b760 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1b770 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1b780 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1b790 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1b7a0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1b7b0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1b7c0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1b7d0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1b7e0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1b7f0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1b800 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1b810 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1b820 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1b830 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1b840 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1b850 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1b860 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1b870 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1b880 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1b890 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1b8a0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1b8b0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1b8c0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1b8d0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1b8e0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1b8f0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1b900 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1b910 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1b920 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1b930 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1b940 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1b950 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1b960 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1b970 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1b980 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1b990 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1b9a0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1b9b0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1b9c0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1b9d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b9e0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1b9f0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1ba00 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ba10 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1ba20 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1ba30 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1ba40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1ba50 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1ba60 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1ba70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1ba80 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1ba90 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1baa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1bab0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1bac0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1bad0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1bae0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1baf0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bb00 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1bb10 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1bb20 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1bb30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1bb40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1bb50 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1bb60 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1bb70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1bb80 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1bb90 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1bba0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1bbb0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1bbc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bbd0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1bbe0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1bbf0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1bc00 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1bc10 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1bc20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1bc30 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1bc40 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1bc50 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1bc60 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1bc70 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1bc80 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1bc90 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1bca0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1bcb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1bcc0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1bcd0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1bce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1bcf0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1bd00 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1bd10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1bd20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1bd30 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1bd40 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1bd50 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1bd60 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1bd70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bd80 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1bd90 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1bda0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1bdb0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1bdc0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1bdd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1bde0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1bdf0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1be00 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1be10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1be20 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1be30 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1be40 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1be50 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1be60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1be70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1be80 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1be90 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1bea0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1beb0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1bec0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1bed0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1bee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bef0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1bf00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1bf10 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1bf20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1bf30 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1bf40 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1bf50 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1bf60 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1bf70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1bf80 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1bf90 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1bfa0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1bfb0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1bfc0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1bfd0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1bfe0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1bff0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1c000 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1c010 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1c020 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  as a [SQLITE_ROL
1c030 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63  LBACK | return c
1c040 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ode].** from the
1c050 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1c060 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1c070 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1c080 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1c090 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1c0a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1c0b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1c0c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c0d0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1c0e0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1c0f0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1c100 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1c110 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1c120 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1c130 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1c140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1c150 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1c160 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1c170 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1c180 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1c190 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1c1a0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1c1b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1c1c0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1c1d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c1e0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1c1f0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1c200 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1c210 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1c220 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1c230 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1c240 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1c250 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1c260 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1c270 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1c280 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1c290 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1c2a0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1c2b0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1c2c0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1c2d0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1c2e0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1c2f0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1c300 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1c310 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1c320 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1c330 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1c340 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1c350 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1c360 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1c370 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1c380 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1c390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c3a0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1c3b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1c3c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1c3d0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1c3e0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1c3f0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1c400 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1c410 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1c420 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1c430 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1c440 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1c450 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1c460 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1c470 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1c480 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1c490 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1c4a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1c4b0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1c4c0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1c4d0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1c4e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c4f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c500 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1c510 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1c520 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1c530 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1c540 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1c550 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c560 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c580 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1c590 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1c5a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c5b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c5c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c5d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c5e0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1c5f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c600 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c620 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1c630 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1c640 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c650 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c670 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1c680 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1c690 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1c6a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c6b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c6c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1c6d0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1c6e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1c6f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c710 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1c720 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1c730 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1c740 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c760 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1c770 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1c780 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1c790 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c7a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1c7b0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1c7c0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1c7d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c7e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c7f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c800 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1c810 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1c820 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1c830 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c840 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c850 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1c860 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1c870 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c880 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c890 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c8a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1c8b0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1c8c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1c8d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c8e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1c8f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1c900 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1c910 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1c920 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c930 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1c940 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1c950 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1c960 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1c970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c980 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1c990 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1c9a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1c9b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c9c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c9d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1c9e0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1c9f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ca00 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ca10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ca20 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1ca30 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1ca40 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ca50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ca60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ca70 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1ca80 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1ca90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1caa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1cab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cac0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1cad0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1cae0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1caf0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1cb00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cb10 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1cb20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1cb30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cb40 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1cb50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cb60 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1cb70 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1cb80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1cb90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cbb0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1cbc0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1cbd0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1cbe0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1cbf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cc00 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1cc10 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1cc20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1cc30 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1cc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1cc50 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1cc60 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1cc70 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1cc80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cc90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1cca0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1ccb0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1ccc0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1ccd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1ccf0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1cd00 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1cd10 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1cd20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1cd30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1cd40 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1cd50 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1cd60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1cd70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cd80 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1cd90 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1cda0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1cdb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1cdc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cdd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1cde0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1cdf0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1ce00 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ce10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ce20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1ce30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1ce40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ce50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1ce60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ce70 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1ce80 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1ce90 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1cea0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1ceb0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1cec0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1ced0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1cee0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1cef0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1cf00 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1cf10 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1cf20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1cf30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1cf40 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1cf50 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1cf60 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1cf70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1cf80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1cf90 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1cfa0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1cfb0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1cfc0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1cfd0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1cfe0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1cff0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1d000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d010 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1d020 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1d030 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1d040 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1d050 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1d060 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1d070 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1d080 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1d090 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d0a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d0b0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1d0c0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1d0d0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1d0e0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1d0f0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1d100 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1d110 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1d120 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1d130 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1d140 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1d150 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1d160 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1d170 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1d180 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1d190 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1d1a0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1d1b0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1d1c0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1d1d0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1d1e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1d1f0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1d200 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1d210 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1d220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1d230 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1d240 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1d250 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1d260 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1d270 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1d280 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1d290 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1d2a0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1d2b0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1d2c0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1d2d0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1d2e0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1d2f0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1d300 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1d310 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1d320 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1d330 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1d340 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1d350 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1d360 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1d370 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1d380 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1d390 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1d3a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1d3b0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1d3c0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1d3d0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1d3e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1d3f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1d400 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1d410 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1d420 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1d430 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1d440 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1d450 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d460 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
1d470 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1d480 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1d490 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1d4a0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1d4b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1d4c0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
1d4d0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1d4e0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1d4f0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1d500 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1d510 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1d520 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1d530 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1d540 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1d550 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1d560 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1d570 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1d580 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1d590 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1d5a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1d5b0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1d5c0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1d5d0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1d5e0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1d5f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1d600 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1d610 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1d620 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d630 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1d640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1d650 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1d660 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1d670 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1d680 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1d690 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1d6a0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1d6b0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1d6c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1d6d0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1d6e0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1d6f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d700 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1d710 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1d720 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1d730 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1d740 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1d750 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1d760 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1d770 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1d780 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1d790 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
1d7a0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1d7b0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1d7c0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1d7d0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1d7e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d7f0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1d800 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1d810 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1d820 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1d830 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1d840 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1d850 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1d860 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1d870 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1d880 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1d890 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1d8a0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1d8b0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1d8c0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1d8d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d8e0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1d8f0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1d900 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1d910 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1d920 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1d930 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1d940 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1d950 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1d960 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1d970 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1d980 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1d990 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1d9a0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1d9b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1d9c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1d9d0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1d9e0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1d9f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1da00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1da10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1da20 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1da30 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1da40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1da50 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1da60 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1da70 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1da80 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
1da90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1daa0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1dab0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1dac0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1dad0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1dae0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1daf0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1db00 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1db10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1db20 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1db30 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
1db40 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
1db50 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1db60 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1db70 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1db80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1db90 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1dba0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1dbb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1dbc0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1dbd0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1dbe0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1dbf0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1dc00 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1dc10 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1dc20 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1dc30 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1dc40 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1dc50 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1dc60 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1dc70 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1dc80 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1dc90 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1dca0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1dcb0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1dcc0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1dcd0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1dce0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1dcf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1dd00 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1dd10 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1dd20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1dd30 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1dd40 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1dd50 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1dd60 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1dd70 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1dd80 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1dd90 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1dda0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1ddb0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1ddc0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1ddd0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1dde0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1ddf0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1de00 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1de10 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1de20 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1de30 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1de40 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1de50 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1de60 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1de70 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1de80 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1de90 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1dea0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1deb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dec0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1ded0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1dee0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1def0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1df00 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1df10 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1df20 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1df30 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1df40 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1df50 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1df60 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1df70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1df80 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1df90 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1dfa0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1dfb0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1dfc0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1dfd0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1dfe0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1dff0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1e000 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1e010 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1e020 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1e030 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1e040 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1e050 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1e060 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1e070 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1e080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1e090 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1e0a0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1e0b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1e0c0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1e0d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1e0e0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1e0f0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1e100 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1e110 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1e120 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1e130 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1e140 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1e150 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
1e160 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1e170 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
1e180 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1e190 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1e1a0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1e1b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1e1c0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1e1d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1e1e0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1e1f0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1e200 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1e210 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1e220 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1e230 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1e240 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1e250 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e260 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1e270 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1e280 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1e290 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1e2a0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1e2b0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1e2c0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1e2d0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1e2e0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1e2f0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1e300 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1e310 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1e320 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1e330 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1e340 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1e350 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1e360 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1e370 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1e380 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1e390 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e3a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1e3b0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1e3c0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1e3d0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
1e3e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1e3f0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1e400 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1e410 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1e420 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1e430 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1e440 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1e450 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1e460 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
1e470 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1e480 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e490 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
1e4a0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
1e4b0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
1e4c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1e4d0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
1e4e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e4f0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
1e500 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
1e510 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1e520 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1e530 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1e540 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1e550 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1e560 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1e580 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1e590 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1e5a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1e5b0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1e5c0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1e5d0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1e5e0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1e5f0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1e600 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1e610 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1e620 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1e630 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1e650 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1e660 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1e670 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1e680 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1e690 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1e6a0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1e6b0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1e6c0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1e6d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1e6e0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1e6f0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1e700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1e710 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1e720 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1e730 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1e740 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1e750 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1e760 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1e770 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1e780 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1e790 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1e7a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1e7b0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1e7c0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1e7d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e7e0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1e7f0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1e800 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1e810 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1e820 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
1e830 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1e840 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1e850 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1e860 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1e870 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1e880 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1e890 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1e8a0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1e8b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1e8c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e8d0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1e8e0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1e8f0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1e900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1e910 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1e920 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1e930 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1e940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1e950 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1e960 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1e970 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1e980 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1e990 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1e9a0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1e9b0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1e9c0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1e9d0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1e9e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1e9f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1ea00 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1ea10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1ea20 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1ea30 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1ea40 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1ea50 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1ea60 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1ea70 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1ea80 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1ea90 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1eaa0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1eab0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1eac0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1ead0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1eae0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1eaf0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1eb00 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1eb10 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1eb20 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1eb30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1eb40 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1eb50 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1eb60 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1eb70 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1eb80 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1eb90 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1eba0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1ebb0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1ebc0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1ebd0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1ebe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1ebf0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
1ec00 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
1ec10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
1ec20 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
1ec30 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
1ec40 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
1ec50 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1ec60 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
1ec70 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1ec80 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
1ec90 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
1eca0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
1ecb0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1ecc0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
1ecd0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
1ece0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1ecf0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
1ed00 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1ed10 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
1ed20 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1ed30 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
1ed40 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
1ed50 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
1ed60 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
1ed70 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
1ed80 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
1ed90 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
1eda0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1edb0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
1edc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
1edd0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
1ede0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
1edf0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
1ee00 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
1ee10 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
1ee20 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
1ee30 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
1ee40 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
1ee50 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
1ee60 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
1ee70 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
1ee80 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
1ee90 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
1eea0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
1eeb0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1eec0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1eed0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
1eee0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
1eef0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
1ef00 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
1ef10 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
1ef20 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
1ef30 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
1ef40 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1ef50 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
1ef60 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
1ef70 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
1ef80 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
1ef90 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
1efa0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
1efb0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1efc0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
1efd0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
1efe0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
1eff0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
1f000 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
1f010 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
1f020 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
1f030 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
1f040 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
1f050 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
1f060 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
1f070 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
1f080 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
1f090 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
1f0a0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
1f0b0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
1f0c0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
1f0d0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
1f0e0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
1f0f0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
1f100 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
1f110 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
1f120 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
1f130 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
1f140 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
1f150 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1f160 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
1f170 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
1f180 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
1f190 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
1f1a0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
1f1b0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
1f1c0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
1f1d0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
1f1e0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
1f1f0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
1f200 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1f210 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
1f220 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
1f230 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
1f240 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
1f250 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
1f260 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
1f270 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
1f280 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
1f290 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
1f2a0 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
1f2b0 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
1f2c0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
1f2d0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
1f2e0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
1f2f0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
1f300 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
1f310 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
1f320 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
1f330 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
1f340 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1f350 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1f360 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
1f370 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
1f380 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1f390 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
1f3a0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
1f3b0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
1f3c0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
1f3d0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
1f3e0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
1f3f0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
1f400 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
1f410 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
1f420 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
1f430 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1f440 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
1f450 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
1f460 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
1f470 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
1f480 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
1f490 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
1f4a0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
1f4b0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
1f4c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1f4d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f4e0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
1f4f0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
1f500 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
1f510 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1f520 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
1f530 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
1f540 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
1f550 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
1f560 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
1f570 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
1f580 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
1f590 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
1f5a0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
1f5b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1f5c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1f5d0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
1f5e0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
1f5f0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1f600 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
1f610 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
1f620 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
1f630 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1f640 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  o sqlite3_prepar
1f650 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  e_v2(). ^If the 
1f660 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
1f670 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
1f680 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
1f690 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f6a0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
1f6b0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
1f6c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1f6d0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
1f6e0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
1f6f0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
1f700 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
1f710 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
1f720 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
1f730 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1f740 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
1f750 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
1f760 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
1f770 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
1f780 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
1f790 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
1f7a0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
1f7b0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
1f7c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
1f7d0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
1f7e0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
1f7f0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
1f800 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
1f810 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
1f820 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
1f830 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
1f840 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
1f850 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
1f860 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
1f870 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
1f880 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
1f890 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1f8a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f8b0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
1f8c0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
1f8d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
1f8e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1f8f0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
1f900 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
1f910 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
1f920 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
1f930 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
1f940 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
1f950 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
1f960 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1f970 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
1f980 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
1f990 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
1f9a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
1f9b0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
1f9c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
1f9d0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
1f9e0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
1f9f0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
1fa00 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1fa10 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
1fa20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
1fa30 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
1fa40 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
1fa50 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
1fa60 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
1fa70 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
1fa80 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
1fa90 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
1faa0 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  ur requested by 
1fab0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
1fac0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1fad0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
1fae0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1faf0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
1fb00 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
1fb10 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
1fb20 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
1fb30 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
1fb40 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
1fb50 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
1fb60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1fb70 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
1fb80 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
1fb90 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
1fba0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
1fbb0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1fbc0 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
1fbd0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
1fbe0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
1fbf0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
1fc00 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
1fc10 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
1fc20 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
1fc30 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
1fc40 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
1fc50 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
1fc60 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
1fc70 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
1fc80 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
1fc90 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
1fca0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1fcb0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
1fcc0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
1fcd0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
1fce0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
1fcf0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
1fd00 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
1fd10 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
1fd20 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1fd30 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
1fd40 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
1fd50 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
1fd60 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
1fd70 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
1fd80 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1fd90 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
1fda0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
1fdb0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
1fdc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1fdd0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
1fde0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
1fdf0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
1fe00 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
1fe10 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
1fe20 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
1fe30 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
1fe40 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
1fe50 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
1fe60 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
1fe70 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
1fe80 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
1fe90 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
1fea0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
1feb0 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
1fec0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
1fed0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
1fee0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
1fef0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
1ff00 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
1ff10 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
1ff20 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
1ff30 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
1ff40 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
1ff50 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
1ff60 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
1ff70 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
1ff80 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
1ff90 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
1ffa0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
1ffb0 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
1ffc0 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
1ffd0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
1ffe0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
1fff0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
20000 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
20010 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
20020 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
20030 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
20040 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
20050 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
20060 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
20070 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
20080 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
20090 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
200a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
200b0 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
200c0 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
200d0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
200e0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
200f0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
20100 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
20110 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
20120 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
20130 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
20140 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20150 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
20160 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
20170 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
20180 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
20190 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
201a0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
201b0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
201c0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
201d0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
201e0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
201f0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
20200 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
20210 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20220 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
20230 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
20240 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
20250 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
20260 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
20270 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
20280 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
20290 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
202a0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
202b0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
202c0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
202d0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
202e0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
202f0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
20300 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
20310 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
20320 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
20330 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
20340 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
20350 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
20360 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
20370 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
20380 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
20390 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
203a0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
203b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
203c0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
203d0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
203e0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
203f0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
20400 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20410 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
20420 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20430 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
20440 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
20450 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
20460 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
20470 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
20480 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
20490 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
204a0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
204b0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
204c0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
204d0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
204e0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
204f0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
20500 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53  _open_v2()..*/.S
20510 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
20520 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
20530 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
20540 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
20550 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
20560 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
20570 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
20580 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
20590 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
205a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
205b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
205c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
205d0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
205e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
205f0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
20600 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
20610 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
20620 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
20630 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
20640 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20650 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
20660 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
20670 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
20680 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
20690 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
206a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
206b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
206c0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
206d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
206e0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
206f0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
20700 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
20710 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
20720 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
20730 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
20740 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
20750 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
20760 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
20770 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
20780 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
20790 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
207a0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
207b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
207c0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
207d0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
207e0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
207f0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
20800 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
20810 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
20820 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
20830 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
20840 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
20850 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
20860 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
20870 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
20880 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
20890 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
208a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
208b0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
208c0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
208d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
208e0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
208f0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
20900 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
20910 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
20920 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
20930 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
20940 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
20950 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
20960 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
20970 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
20980 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
20990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
209a0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
209b0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
209c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
209d0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
209e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
209f0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
20a00 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
20a10 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
20a20 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
20a30 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
20a40 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
20a50 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
20a60 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
20a70 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
20a80 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
20a90 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
20aa0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
20ab0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
20ac0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
20ad0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
20ae0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
20af0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
20b00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
20b10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
20b20 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
20b30 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
20b40 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
20b50 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
20b60 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
20b70 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
20b80 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
20b90 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
20ba0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
20bb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
20bc0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
20bd0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
20be0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
20bf0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
20c00 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
20c10 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
20c20 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
20c30 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
20c40 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
20c50 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
20c60 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
20c70 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
20c80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
20c90 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
20ca0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
20cb0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
20cc0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
20cd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
20ce0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
20cf0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
20d00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20d10 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
20d20 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
20d30 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
20d40 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
20d50 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20d60 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
20d70 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
20d80 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
20d90 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
20da0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
20db0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
20dc0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
20dd0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
20de0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
20df0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
20e00 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
20e10 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
20e20 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
20e30 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
20e40 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20e50 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
20e60 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
20e70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
20e80 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
20e90 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
20ea0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
20eb0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
20ec0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
20ed0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
20ee0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20ef0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
20f00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20f10 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
20f20 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
20f30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
20f40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
20f50 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
20f60 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
20f70 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
20f80 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
20f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
20fa0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
20fb0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
20fc0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
20fd0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
20fe0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
20ff0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
21000 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
21010 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
21020 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
21030 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
21040 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
21050 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
21060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21070 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
21080 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21090 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
210a0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
210b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
210c0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
210d0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
210e0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
210f0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
21100 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
21110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
21120 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
21130 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
21140 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
21150 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
21160 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
21170 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
21180 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
21190 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
211a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
211b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
211c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
211d0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
211e0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
211f0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
21200 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
21210 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
21220 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
21230 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
21240 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
21250 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
21260 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
21270 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
21280 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
21290 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
212a0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
212b0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
212c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
212d0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
212e0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
212f0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
21300 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
21310 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
21320 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
21330 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
21340 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
21350 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
21360 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
21370 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
21380 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
21390 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
213a0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
213b0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
213c0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
213d0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
213e0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
213f0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
21400 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
21410 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
21420 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
21430 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
21440 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
21450 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
21460 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
21470 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
21480 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
21490 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
214a0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
214b0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
214c0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
214d0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
214e0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
214f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
21500 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
21510 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
21520 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
21530 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
21540 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
21550 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
21560 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
21570 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
21580 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
21590 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
215a0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
215b0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
215c0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
215d0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
215e0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
215f0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
21600 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
21610 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
21620 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
21630 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
21640 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
21650 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
21660 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
21670 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
21680 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
21690 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
216a0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
216b0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
216c0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
216d0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
216e0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
216f0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
21700 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
21710 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
21720 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
21730 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
21740 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
21750 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
21760 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
21770 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
21780 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21790 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
217a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
217b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
217c0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
217d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
217e0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
217f0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
21800 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
21810 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
21820 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21830 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
21840 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
21850 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
21860 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
21870 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
21880 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
21890 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
218a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
218b0 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
218c0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
218d0 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
218e0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
218f0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
21900 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
21910 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
21920 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
21930 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
21940 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
21950 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
21960 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21970 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
21980 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
21990 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
219a0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
219b0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
219c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
219d0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
219e0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
219f0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
21a00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21a10 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
21a20 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
21a30 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
21a40 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
21a50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
21a60 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
21a70 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
21a80 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
21a90 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
21aa0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
21ab0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
21ac0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21ad0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
21ae0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
21af0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
21b00 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
21b10 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
21b20 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21b30 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
21b40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
21b50 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
21b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21b70 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
21b80 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
21b90 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
21ba0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
21bb0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
21bc0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
21bd0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
21be0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
21bf0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
21c00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
21c10 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
21c20 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
21c30 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
21c40 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
21c50 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
21c60 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
21c70 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
21c80 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
21c90 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
21ca0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
21cb0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
21cc0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
21cd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
21ce0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
21cf0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
21d00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
21d10 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
21d20 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
21d30 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
21d40 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
21d50 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
21d60 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
21d70 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
21d80 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
21d90 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
21da0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
21db0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
21dc0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
21dd0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
21de0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
21df0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
21e00 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
21e10 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
21e20 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
21e30 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
21e40 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
21e50 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
21e60 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
21e70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
21e80 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
21e90 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
21ea0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
21eb0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
21ec0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
21ed0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
21ee0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
21ef0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
21f00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21f10 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
21f20 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
21f30 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
21f40 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
21f50 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
21f60 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
21f70 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
21f80 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
21f90 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
21fa0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
21fb0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
21fc0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
21fd0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
21fe0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
21ff0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
22000 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
22010 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
22020 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
22030 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
22040 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
22050 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
22060 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
22070 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
22080 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
22090 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
220a0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
220b0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
220c0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
220d0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
220e0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
220f0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
22100 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
22110 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
22120 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
22130 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
22140 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
22150 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
22160 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
22170 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
22180 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
22190 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
221a0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
221b0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
221c0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
221d0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
221e0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
221f0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
22200 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
22210 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
22220 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
22230 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
22240 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
22250 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
22260 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
22270 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
22280 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
22290 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
222a0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
222b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
222c0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
222d0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
222e0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
222f0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
22300 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
22310 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53  e releases..*/.S
22320 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
22330 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
22340 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
22350 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
22360 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
22370 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
22380 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
22390 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
223a0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
223b0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
223c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
223d0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
223e0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
223f0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
22400 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
22410 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
22420 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
22430 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
22440 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
22450 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
22460 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
22470 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
22480 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
22490 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
224a0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
224b0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
224c0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
224d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
224e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
224f0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
22500 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22510 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
22520 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
22530 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
22540 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
22550 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
22560 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
22570 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
22580 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
22590 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
225a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
225b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
225c0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
225d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
225e0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
225f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22600 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
22610 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22620 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22630 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
22640 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
22650 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
22660 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
22670 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
22680 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
22690 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
226a0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
226b0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
226c0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
226d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
226e0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
226f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
22700 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
22710 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22720 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
22730 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
22740 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
22750 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22760 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
22770 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
22780 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
22790 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
227a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
227b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
227c0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
227d0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
227e0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
227f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
22800 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
22810 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
22820 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
22830 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22840 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
22850 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
22860 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
22870 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
22880 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
22890 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
228a0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
228b0 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
228c0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
228d0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
228e0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
228f0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
22900 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
22910 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22920 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
22930 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
22940 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
22950 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
22960 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22970 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
22980 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
22990 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
229a0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
229b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
229c0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
229d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
229e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
229f0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
22a00 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
22a10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
22a20 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
22a30 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
22a40 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
22a50 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
22a60 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
22a70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22a80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
22a90 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
22aa0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
22ab0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
22ac0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
22ad0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22ae0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22af0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
22b00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
22b10 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
22b20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22b30 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
22b40 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
22b50 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
22b60 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
22b70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
22b80 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
22b90 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
22ba0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
22bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22bc0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
22bd0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
22be0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
22bf0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
22c00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22c10 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
22c20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
22c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22c40 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
22c50 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
22c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22c70 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
22c80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
22c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22ca0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
22cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
22cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22cd0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
22ce0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
22cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d00 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
22d10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22d20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
22d30 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
22d40 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
22d50 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
22d60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
22d70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22d80 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
22d90 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
22da0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
22db0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
22dc0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
22dd0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
22de0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
22df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
22e00 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
22e10 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
22e20 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
22e30 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
22e40 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
22e50 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
22e60 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
22e70 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
22e80 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
22e90 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
22ea0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
22eb0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
22ec0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
22ed0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
22ee0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
22ef0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
22f00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22f10 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
22f20 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
22f30 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
22f40 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
22f50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
22f60 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
22f70 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
22f80 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
22f90 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
22fa0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
22fb0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
22fc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
22fd0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
22fe0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
22ff0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
23000 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
23010 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
23020 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
23030 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
23040 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
23050 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
23060 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
23070 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
23080 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
23090 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
230a0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
230b0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
230c0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
230d0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
230e0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
230f0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
23100 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
23110 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
23120 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
23130 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
23140 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
23150 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
23160 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
23170 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
23180 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
23190 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
231a0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
231b0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
231c0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
231d0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
231e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
231f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
23200 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
23210 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
23220 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
23230 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
23240 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
23250 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
23260 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
23270 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
23280 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
23290 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
232a0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
232b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
232c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
232d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
232e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
232f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
23300 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
23310 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
23320 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
23330 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
23340 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
23350 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
23360 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
23370 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
23380 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
23390 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
233a0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
233b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
233c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
233d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
233e0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
233f0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
23400 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
23410 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
23420 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
23430 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
23440 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
23450 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
23460 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
23470 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
23480 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
23490 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
234a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
234b0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
234c0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
234d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
234e0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
234f0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
23500 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
23510 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
23520 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
23530 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
23540 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
23550 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
23560 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
23570 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
23580 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
23590 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
235a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
235b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
235c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
235d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
235e0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
235f0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
23600 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
23610 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
23620 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
23630 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
23640 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
23650 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
23660 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
23670 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
23680 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23690 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
236a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
236b0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
236c0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
236d0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
236e0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
236f0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
23700 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
23710 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
23720 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
23730 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
23740 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
23750 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
23760 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
23770 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
23780 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
23790 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
237a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
237b0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
237c0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
237d0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
237e0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
237f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23800 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
23810 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
23820 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
23830 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
23840 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
23850 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
23860 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
23870 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
23880 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
23890 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
238a0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
238b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
238c0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
238d0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
238e0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
238f0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
23900 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69  t again..** </li
23910 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
23920 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
23930 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
23940 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
23950 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
23960 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
23970 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
23980 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
23990 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
239a0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
239b0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
239c0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
239d0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
239e0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
239f0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
23a00 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
23a10 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
23a20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
23a30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
23a40 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
23a50 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
23a60 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
23a70 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
23a80 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
23a90 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
23aa0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
23ab0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
23ac0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
23ad0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
23ae0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
23af0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
23b00 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
23b10 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
23b20 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
23b30 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
23b40 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
23b50 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
23b60 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
23b70 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
23b80 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
23b90 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
23ba0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
23bb0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
23bc0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
23bd0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
23be0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
23bf0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
23c00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
23c10 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
23c20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
23c30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
23c40 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
23c50 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
23c60 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
23c70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
23c80 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
23c90 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
23ca0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
23cb0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
23cc0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
23cd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
23ce0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
23cf0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
23d00 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
23d10 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
23d20 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
23d30 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
23d40 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
23d50 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
23d60 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
23d70 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
23d80 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20  led..** the .** 
23d90 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
23da0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
23db0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23dc0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
23dd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
23de0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
23df0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
23e00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
23e10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
23e20 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
23e30 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
23e40 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
23e50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
23e60 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
23e70 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
23e80 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
23e90 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
23ea0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
23eb0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
23ec0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
23ed0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
23ee0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
23ef0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
23f00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23f10 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
23f20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
23f30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
23f40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23f50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
23f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
23f70 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
23f80 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
23f90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
23fa0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
23fb0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
23fc0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
23fd0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
23fe0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
23ff0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
24000 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
24010 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
24020 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
24030 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
24040 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
24050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24060 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
24070 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
24080 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
24090 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
240a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
240b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
240c0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
240d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
240e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
240f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24100 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
24110 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
24120 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
24130 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
24140 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24150 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
24160 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
24170 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
24180 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
24190 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
241a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
241b0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
241c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
241d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
241e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
241f0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
24200 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
24210 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
24220 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
24230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24240 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
24250 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
24260 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
24270 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
24280 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
24290 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
242a0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
242b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
242c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
242d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
242e0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
242f0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
24300 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
24310 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
24320 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
24330 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
24340 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
24350 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
24360 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
24370 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
24380 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
24390 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
243a0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
243b0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
243c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
243d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
243e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
243f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
24400 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24410 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
24420 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
24430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
24440 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
24450 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
24460 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
24470 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24480 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24490 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
244a0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
244b0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
244c0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
244d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
244e0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
244f0 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
24500 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
24510 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24520 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
24530 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
24540 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
24550 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
24560 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
24570 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
24580 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
24590 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
245a0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
245b0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
245c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
245d0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
245e0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
245f0 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
24600 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
24610 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
24620 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
24630 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24640 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
24650 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
24660 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
24670 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
24680 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
24690 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
246a0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
246b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
246c0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
246d0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
246e0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
246f0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
24700 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
24710 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
24720 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
24730 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
24740 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
24750 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
24760 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
24770 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
24780 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
24790 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
247a0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
247b0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
247c0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
247d0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
247e0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
247f0 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
24800 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
24810 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
24820 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
24830 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
24840 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
24850 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
24860 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
24870 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
24880 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
24890 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
248a0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
248b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
248c0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
248d0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
248e0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
248f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
24900 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
24910 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
24920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
24930 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
24940 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
24950 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
24960 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
24970 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c   on disk..*/.SQL
24980 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24990 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
249a0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
249b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
249c0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
249d0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
249e0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
249f0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
24a00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
24a10 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
24a20 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
24a30 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
24a40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24a50 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
24a60 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
24a70 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
24a80 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
24a90 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
24aa0 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
24ab0 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
24ac0 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
24ad0 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
24ae0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
24af0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
24b00 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
24b10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
24b20 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
24b30 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
24b40 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
24b50 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
24b60 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
24b70 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
24b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24b90 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
24ba0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
24bb0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24bc0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
24bd0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
24be0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
24bf0 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
24c00 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
24c10 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
24c20 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
24c30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
24c40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24c50 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
24c60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
24c70 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
24c80 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
24c90 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
24ca0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
24cb0 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
24cc0 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
24cd0 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
24ce0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
24cf0 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
24d00 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
24d10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
24d20 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
24d30 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
24d40 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24d50 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
24d60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
24d70 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24d80 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
24d90 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
24da0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24db0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
24dc0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
24dd0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24de0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
24df0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
24e00 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
24e10 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
24e20 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
24e30 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
24e40 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
24e50 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
24e60 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
24e70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24e80 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
24e90 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
24ea0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
24eb0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
24ec0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
24ed0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
24ee0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
24ef0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
24f00 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
24f10 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
24f20 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
24f30 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
24f40 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
24f50 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
24f60 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
24f70 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
24f80 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
24f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
24fa0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
24fb0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
24fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
24fd0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
24fe0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
24ff0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
25000 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
25010 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
25020 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
25030 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
25040 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
25050 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
25060 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
25070 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
25080 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
25090 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
250a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
250b0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
250c0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
250d0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
250e0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
250f0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
25100 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
25110 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
25120 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
25130 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
25140 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
25150 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
25160 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
25170 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
25180 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
25190 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
251a0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
251b0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
251c0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
251d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
251e0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
251f0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
25200 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
25210 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
25220 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
25230 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
25240 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
25250 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
25260 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
25270 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
25280 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
25290 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
252a0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
252b0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
252c0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
252d0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
252e0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
252f0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
25300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
25310 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
25320 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
25330 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25340 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
25350 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
25360 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
25370 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
25380 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
25390 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
253a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
253b0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
253c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
253d0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
253e0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
253f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25400 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
25410 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
25420 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25430 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
25440 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
25450 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
25460 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
25470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25480 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
25490 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
254a0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
254b0 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
254c0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
254d0 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
254e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
254f0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
25500 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
25510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
25520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25530 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
25540 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
25550 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
25560 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
25570 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
25580 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
25590 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
255a0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
255b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
255c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
255d0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
255e0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
255f0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
25600 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
25610 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
25620 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
25630 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25640 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
25650 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
25660 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
25670 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
25680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
25690 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
256a0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
256b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
256c0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
256d0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
256e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
256f0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
25700 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
25710 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
25720 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
25730 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
25740 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
25750 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
25760 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
25770 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
25780 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
25790 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
257a0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
257b0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
257c0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
257d0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
257e0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
257f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
25800 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
25810 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
25820 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
25830 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
25840 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
25850 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
25860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25870 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
25880 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
25890 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
258a0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
258b0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
258c0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
258d0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
258e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
258f0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
25900 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
25910 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
25920 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
25930 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
25940 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
25950 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
25960 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
25970 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
25980 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
25990 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
259a0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
259b0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
259c0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
259d0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
259e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
259f0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
25a00 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
25a10 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
25a20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25a30 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
25a40 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
25a50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25a60 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
25a70 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
25a80 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
25a90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25aa0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
25ab0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
25ac0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
25ad0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25ae0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
25af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
25b00 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
25b10 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
25b20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
25b30 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
25b40 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
25b50 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
25b60 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
25b70 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
25b80 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
25b90 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
25ba0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
25bb0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
25bc0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
25bd0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
25be0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
25bf0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
25c00 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
25c10 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
25c20 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
25c30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
25c40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25c50 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
25c60 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
25c70 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
25c80 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
25c90 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
25ca0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
25cb0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
25cc0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
25cd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
25ce0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
25cf0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
25d00 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25d10 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
25d20 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
25d30 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
25d40 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
25d50 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
25d60 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
25d70 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
25d80 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
25d90 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
25da0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
25db0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
25dc0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
25dd0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
25de0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
25df0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
25e00 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
25e10 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
25e20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
25e30 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
25e40 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
25e50 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
25e60 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
25e70 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
25e80 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
25e90 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
25ea0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
25eb0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
25ec0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
25ed0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25ee0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
25ef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25f00 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
25f10 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
25f20 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
25f30 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
25f40 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
25f50 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
25f60 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
25f70 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
25f80 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
25f90 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
25fa0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
25fb0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
25fc0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
25fd0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
25fe0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
25ff0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
26000 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
26010 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
26020 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
26030 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
26040 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
26050 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
26060 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
26070 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
26080 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26090 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
260a0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
260b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
260c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
260d0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
260e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
260f0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
26100 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
26110 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
26120 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
26130 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
26140 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
26150 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
26160 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
26170 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
26180 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
26190 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
261a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
261b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
261c0 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
261d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
261e0 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
261f0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
26200 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
26210 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
26220 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
26230 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
26240 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
26250 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
26260 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
26270 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
26280 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
26290 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
262a0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
262b0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
262c0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
262d0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
262e0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
262f0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
26300 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
26310 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
26320 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
26330 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
26340 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
26350 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
26360 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
26370 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
26380 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
26390 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
263a0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
263b0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
263c0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
263d0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
263e0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
263f0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
26400 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
26410 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
26420 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
26430 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
26440 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
26450 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
26460 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
26470 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
26480 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
26490 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
264a0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
264b0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
264c0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
264d0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
264e0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
264f0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
26500 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
26510 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
26520 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
26530 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
26540 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
26550 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26560 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
26570 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
26580 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
26590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
265a0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
265b0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
265c0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
265d0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
265e0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
265f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
26600 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
26610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
26620 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
26630 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
26640 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
26650 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
26660 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
26670 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
26680 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
26690 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
266a0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
266b0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
266c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
266d0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
266e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
266f0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
26700 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
26710 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
26720 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
26730 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
26740 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
26750 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
26760 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
26770 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
26780 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
26790 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
267a0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
267b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
267c0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
267d0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
267e0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
267f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
26800 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
26810 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
26820 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
26830 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26840 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
26850 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26860 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
26870 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
26890 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
268a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
268b0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
268c0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
268d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
268e0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
268f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26900 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
26910 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26920 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
26930 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
26940 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
26950 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26960 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
26970 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
26980 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
26990 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
269a0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
269b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
269c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
269d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
269e0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
269f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
26a00 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
26a10 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
26a20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26a30 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
26a40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26a50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
26a60 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
26a70 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
26a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26a90 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
26aa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26ab0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
26ac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26ad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
26ae0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
26af0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
26b00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26b10 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
26b20 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
26b30 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
26b40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
26b50 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
26b60 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
26b70 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
26b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26b90 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
26ba0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
26bb0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
26bc0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
26bd0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
26be0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
26bf0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
26c00 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
26c10 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
26c20 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
26c30 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
26c40 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
26c50 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
26c60 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
26c70 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
26c80 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
26c90 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
26ca0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
26cb0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
26cc0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
26cd0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
26ce0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
26cf0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
26d00 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
26d10 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
26d20 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
26d30 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
26d40 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
26d50 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
26d60 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
26d70 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
26d80 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
26d90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26da0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
26db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26dc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
26dd0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
26de0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26df0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
26e00 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
26e10 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26e20 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
26e30 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
26e40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26e50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26e60 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
26e70 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
26e80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26e90 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
26ea0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
26eb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26ec0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
26ed0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
26ee0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
26ef0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
26f00 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
26f10 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
26f20 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
26f30 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
26f40 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
26f50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
26f60 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
26f70 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
26f80 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
26f90 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
26fa0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
26fb0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
26fc0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
26fd0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
26fe0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
26ff0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
27000 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
27010 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
27020 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
27030 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
27040 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
27050 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
27060 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
27070 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
27080 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27090 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
270a0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
270b0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
270c0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
270d0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
270e0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
270f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27100 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
27110 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
27120 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
27130 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
27140 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
27150 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
27160 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
27170 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
27180 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27190 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
271a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
271b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
271c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
271d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
271e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
271f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27200 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27210 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
27220 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27230 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
27240 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
27250 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27260 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
27270 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
27280 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
27290 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
272a0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
272b0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
272c0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
272d0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
272e0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
272f0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
27300 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
27310 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
27320 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
27330 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
27340 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
27350 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
27360 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
27370 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
27380 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
27390 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
273a0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
273b0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
273c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
273d0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
273e0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
273f0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
27400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27410 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
27420 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27430 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
27440 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
27450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27460 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
27470 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
27480 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
27490 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
274a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
274b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
274c0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
274d0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
274e0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
274f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
27500 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
27510 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
27520 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
27530 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
27540 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
27550 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27560 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
27570 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
27580 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
27590 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
275a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
275b0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
275c0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
275d0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
275e0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
275f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27600 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
27610 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
27620 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
27630 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
27640 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
27650 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
27660 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
27670 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
27680 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
27690 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
276a0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
276b0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
276c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
276d0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
276e0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
276f0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
27700 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
27710 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
27720 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
27730 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
27740 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
27750 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
27770 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
27780 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27790 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
277a0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
277b0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
277c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
277d0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
277e0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
277f0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
27800 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
27810 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
27820 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
27830 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27840 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
27850 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
27860 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
27870 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
27880 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
27890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
278a0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
278b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
278c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
278d0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
278e0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
278f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
27900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27910 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
27920 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
27930 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
27940 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
27950 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
27960 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
27970 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
27980 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
27990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
279a0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
279b0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
279c0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
279d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
279e0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
279f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
27a00 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
27a10 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
27a20 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
27a30 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
27a40 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
27a50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
27a60 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
27a70 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
27a80 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
27a90 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
27aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
27ab0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
27ac0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
27ad0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
27ae0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
27af0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
27b00 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
27b10 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
27b20 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
27b30 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
27b40 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
27b50 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
27b60 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
27b70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
27b80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
27b90 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
27ba0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
27bb0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
27bc0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
27bd0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
27be0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
27bf0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
27c00 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
27c10 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
27c20 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
27c30 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
27c40 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
27c50 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
27c60 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
27c70 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
27c80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27c90 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
27ca0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
27cb0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
27cc0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27cd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
27ce0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
27cf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
27d00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27d10 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
27d20 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
27d30 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
27d40 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
27d50 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
27d60 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
27d70 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
27d80 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
27d90 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
27da0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
27db0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
27dc0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
27dd0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
27de0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
27df0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
27e00 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
27e10 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
27e20 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
27e30 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
27e40 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
27e50 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
27e60 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
27e70 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
27e80 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
27e90 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
27ea0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
27eb0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
27ec0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
27ed0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
27ee0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
27ef0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
27f00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27f10 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
27f20 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
27f30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27f40 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
27f50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
27f60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
27f70 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
27f80 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
27f90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27fa0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
27fb0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
27fc0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
27fd0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
27fe0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
27ff0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
28000 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
28010 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
28020 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
28030 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
28040 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
28050 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
28060 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
28070 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
28080 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
28090 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
280a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
280b0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
280c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
280d0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
280e0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
280f0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
28100 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
28110 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
28120 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
28130 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
28140 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
28150 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
28160 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
28170 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
28180 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
28190 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
281a0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
281b0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
281c0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
281d0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
281e0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
281f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
28200 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
28210 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
28220 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
28230 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
28240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
28250 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
28260 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
28270 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
28280 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
28290 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
282a0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
282b0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
282c0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
282d0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
282e0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
282f0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
28300 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
28310 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
28320 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
28330 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
28340 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
28350 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
28360 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
28370 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
28380 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
28390 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
283a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
283b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
283c0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
283d0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
283e0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
283f0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
28400 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28410 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
28420 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
28430 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
28440 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28450 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
28460 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
28470 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28480 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
28490 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
284a0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
284b0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
284c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
284d0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
284e0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
284f0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
28500 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
28510 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28520 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
28530 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
28540 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
28550 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
28570 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
28580 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
28590 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
285a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
285b0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
285c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
285d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
285e0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
285f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
28600 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28610 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
28620 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
28630 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28640 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
28650 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28660 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
28670 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
28680 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
28690 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
286a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
286b0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
286c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
286d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
286e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
286f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
28700 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
28710 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
28720 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
28730 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
28740 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
28750 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
28760 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
28770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28780 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
28790 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
287a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
287b0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
287c0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
287d0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
287e0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
287f0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
28800 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
28810 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28820 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
28830 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
28840 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
28850 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
28860 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
28870 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
28880 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
28890 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
288a0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
288b0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
288c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
288d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
288e0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
288f0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
28900 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
28910 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
28920 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
28930 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
28940 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
28950 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
28960 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
28970 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
28980 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
28990 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
289a0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
289b0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
289c0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
289d0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
289e0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
289f0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
28a00 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
28a10 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
28a20 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
28a30 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
28a40 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
28a50 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
28a60 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
28a70 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
28a80 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
28a90 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
28aa0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
28ab0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
28ac0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
28ad0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
28ae0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
28af0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
28b00 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
28b10 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
28b20 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
28b30 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
28b40 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
28b50 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
28b60 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
28b70 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
28b80 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
28b90 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
28ba0 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lues..*/.SQLITE_
28bb0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
28bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28bd0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
28be0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
28bf0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
28c00 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28c10 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
28c20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28c30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28c40 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
28c50 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
28c60 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
28c70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
28c80 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
28c90 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
28ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28cb0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
28cc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28cd0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
28ce0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
28cf0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
28d00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
28d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28d20 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
28d30 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
28d40 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
28d50 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
28d60 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
28d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
28d80 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
28d90 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
28da0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
28db0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
28dc0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
28dd0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
28de0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
28df0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
28e00 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
28e10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
28e20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28e30 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
28e40 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
28e50 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
28e60 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
28e70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28e80 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
28e90 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
28ea0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
28eb0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
28ec0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
28ed0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
28ee0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
28ef0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
28f00 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
28f10 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
28f20 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
28f30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28f40 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
28f50 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
28f60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
28f70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
28f80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
28f90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
28fa0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
28fb0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
28fc0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
28fd0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
28fe0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
28ff0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
29000 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
29010 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
29020 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
29030 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
29040 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
29050 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
29060 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
29070 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
29080 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
29090 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
290a0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
290b0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
290c0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
290d0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
290e0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
290f0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
29100 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
29110 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
29120 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
29130 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
29140 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
29150 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
29160 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
29170 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
29180 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
29190 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
291a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
291b0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
291c0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
291d0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
291e0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
291f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
29200 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
29210 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
29220 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
29230 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
29240 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29250 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
29260 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
29270 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
29280 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
29290 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
292a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
292b0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
292c0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
292d0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
292e0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
292f0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
29300 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
29310 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
29320 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
29330 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
29340 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
29350 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
29360 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
29370 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
29380 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
29390 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
293a0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
293b0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
293c0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
293d0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
293e0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
293f0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
29400 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
29410 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
29420 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
29430 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
29440 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
29450 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
29460 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
29470 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
29480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
29490 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
294a0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
294b0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
294c0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
294d0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
294e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
294f0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
29500 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
29510 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
29520 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
29530 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
29540 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
29550 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
29560 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29570 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
29580 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
29590 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
295a0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
295b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
295c0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
295d0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
295e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
295f0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
29600 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
29610 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
29620 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
29630 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
29640 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
29650 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29660 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
29670 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
29680 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
29690 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
296a0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
296b0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
296c0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
296d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
296e0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
296f0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
29700 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
29720 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
29730 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
29740 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
29750 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
29760 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
29770 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
29780 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
29790 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
297a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
297b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
297c0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
297d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
297e0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
297f0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
29800 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
29810 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
29820 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
29830 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29840 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
29850 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
29860 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
29870 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
29880 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
29890 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
298a0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
298b0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
298c0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
298d0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
298e0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
298f0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
29900 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29910 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
29920 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
29930 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
29940 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
29950 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
29960 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
29970 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
29980 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
29990 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
299a0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
299b0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
299c0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
299d0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
299e0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
299f0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
29a00 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
29a10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
29a20 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
29a30 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
29a40 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
29a50 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
29a60 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
29a70 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
29a80 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
29a90 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
29aa0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
29ab0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
29ac0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
29ad0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
29ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
29af0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
29b00 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
29b10 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
29b20 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
29b30 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
29b40 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
29b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29b60 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
29b70 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
29b80 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
29b90 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
29ba0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
29bb0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
29bc0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
29bd0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
29be0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
29bf0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
29c00 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
29c10 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
29c20 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
29c30 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
29c40 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
29c50 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
29c60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29c80 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
29c90 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
29ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29cb0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29cc0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
29cd0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
29ce0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
29cf0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
29d00 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
29d10 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
29d20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
29d30 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
29d40 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
29d50 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
29d60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29d70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
29d80 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29da0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29db0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
29dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29dd0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
29de0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29df0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
29e00 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
29e10 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
29e20 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29e30 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
29e40 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
29e50 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
29e60 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
29e70 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
29e80 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
29e90 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
29ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
29eb0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
29ec0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
29ed0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
29ee0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
29ef0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
29f00 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
29f10 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29f20 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
29f30 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
29f40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29f50 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
29f60 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
29f70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
29f80 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
29f90 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
29fa0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
29fb0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
29fc0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
29fd0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29fe0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
29ff0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2a000 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2a010 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2a020 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2a030 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2a040 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2a050 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2a060 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2a070 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2a080 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2a090 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2a0a0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2a0b0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2a0c0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2a0d0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2a0e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2a0f0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2a100 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2a110 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2a120 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a130 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2a150 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2a160 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2a170 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2a180 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2a190 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2a1a0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2a1b0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2a1c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a1d0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2a1e0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2a1f0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2a200 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2a210 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2a220 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2a230 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2a240 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2a250 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2a260 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2a270 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2a280 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2a290 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2a2a0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2a2b0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2a2c0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2a2d0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2a2e0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2a2f0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2a300 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2a310 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2a320 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2a330 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2a340 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2a350 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2a360 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2a370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2a380 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2a390 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2a3a0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2a3b0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2a3c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2a3d0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2a3e0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2a3f0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2a400 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2a410 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2a420 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2a430 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2a440 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a450 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2a460 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2a470 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2a480 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a490 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2a4a0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2a4b0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2a4c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2a4d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2a4e0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2a4f0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2a500 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2a510 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2a520 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2a530 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2a540 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2a550 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2a560 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2a570 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a580 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2a590 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2a5a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2a5b0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2a5c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2a5d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2a5e0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2a5f0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2a600 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2a610 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2a620 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2a630 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2a640 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2a650 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2a660 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2a670 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a680 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2a690 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2a6a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2a6b0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2a6c0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2a6d0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2a6e0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2a6f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2a700 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2a710 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2a720 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2a730 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2a740 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2a750 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2a760 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2a770 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2a780 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2a790 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2a7a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2a7b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2a7c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a7d0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2a7e0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2a7f0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2a800 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2a810 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a820 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2a830 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2a840 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2a850 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2a860 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2a870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a880 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2a890 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2a8a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2a8b0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2a8c0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2a8d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2a8e0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2a8f0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2a900 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2a910 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2a920 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a930 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a940 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2a950 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2a960 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2a970 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2a980 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2a990 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2a9a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2a9b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2a9c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a9d0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2a9e0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a9f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2aa00 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2aa10 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2aa20 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2aa30 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2aa40 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2aa50 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2aa60 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2aa70 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2aa80 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2aa90 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2aaa0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2aab0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2aac0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2aad0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2aae0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2aaf0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2ab00 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2ab10 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2ab20 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2ab30 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2ab40 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2ab50 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2ab60 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ab70 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2ab80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2ab90 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2aba0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2abb0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2abc0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2abd0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2abe0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2abf0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2ac00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2ac10 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2ac20 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2ac30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2ac40 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2ac50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ac60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ac70 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2ac80 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2ac90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2aca0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2acb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2acc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2acd0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2ace0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2acf0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ad00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ad10 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2ad20 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ad30 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2ad40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ad50 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2ad60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2ad70 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2ad80 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2ad90 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2ada0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2adb0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2adc0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2add0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ade0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2adf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ae00 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2ae10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2ae20 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2ae30 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2ae40 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2ae50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ae60 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2ae70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ae80 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ae90 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2aea0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2aeb0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2aec0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2aed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2aee0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2aef0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2af00 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2af10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2af20 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2af30 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2af40 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2af50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2af60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2af70 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2af80 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2af90 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2afa0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2afb0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2afc0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2afd0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2afe0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2aff0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2b000 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2b010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b020 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2b030 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2b040 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b060 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2b070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b080 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2b090 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2b0a0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2b0b0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2b0c0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2b0d0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2b0e0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2b0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2b100 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2b110 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b120 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2b130 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2b140 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2b150 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2b160 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2b170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2b180 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2b190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b1a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2b1b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2b1c0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2b1d0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2b1e0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2b1f0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2b200 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2b210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b220 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2b230 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2b240 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b250 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2b260 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2b280 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2b290 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b2a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b2b0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2b2c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b2d0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2b2e0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2b2f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2b300 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2b310 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2b320 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2b330 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2b340 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b350 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2b360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2b370 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2b380 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2b390 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2b3a0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2b3b0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2b3c0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2b3d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2b3e0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2b3f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2b400 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2b410 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2b420 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2b430 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2b440 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2b450 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2b460 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2b470 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2b480 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2b490 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2b4a0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2b4b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2b4c0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2b4d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2b4e0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2b4f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2b500 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2b510 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2b520 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2b530 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2b540 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2b550 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2b560 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2b570 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2b580 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2b590 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2b5a0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2b5b0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2b5c0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2b5d0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2b5e0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2b5f0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2b600 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2b610 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b620 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b630 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2b640 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b650 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2b660 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b670 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2b680 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b690 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2b6a0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b6b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2b6c0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b6d0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2b6e0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2b6f0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2b700 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2b710 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2b720 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2b730 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2b740 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2b750 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2b760 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2b770 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2b780 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2b790 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b7a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b7b0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2b7c0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
2b7d0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2b7e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2b7f0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2b800 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2b810 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2b820 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b830 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b840 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
2b850 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2b860 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2b870 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
2b880 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2b890 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2b8a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b8b0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
2b8c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2b8d0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2b8e0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2b8f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2b900 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2b910 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2b920 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2b930 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2b940 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2b950 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b960 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2b970 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
2b980 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b990 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2b9a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2b9b0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2b9c0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2b9d0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2b9e0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2b9f0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2ba00 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2ba10 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2ba20 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2ba30 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2ba40 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2ba50 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2ba60 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2ba70 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2ba80 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2ba90 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2baa0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2bab0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2bac0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2bad0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2bae0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2baf0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2bb00 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2bb10 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2bb20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2bb30 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2bb40 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2bb50 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2bb60 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2bb70 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2bb80 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2bb90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2bba0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2bbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bbc0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2bbd0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2bbe0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2bbf0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2bc00 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2bc10 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2bc20 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2bc30 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2bc40 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2bc50 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2bc60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bc70 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2bc80 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2bc90 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2bca0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2bcb0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2bcc0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2bcd0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2bce0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2bcf0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2bd00 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2bd10 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2bd20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2bd30 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2bd40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bd50 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2bd60 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2bd70 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2bd80 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2bd90 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2bda0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2bdb0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2bdc0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2bdd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2bde0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2bdf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2be00 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2be10 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2be20 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2be30 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2be40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2be50 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2be60 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2be70 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2be80 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2be90 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2bea0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2beb0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2bec0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2bed0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2bee0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2bef0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2bf00 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2bf10 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2bf20 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2bf30 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2bf40 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2bf50 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2bf60 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2bf70 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2bf80 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2bf90 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2bfa0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2bfb0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2bfc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2bfd0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2bfe0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2bff0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2c000 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2c010 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2c020 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2c030 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2c040 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c050 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2c060 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c070 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2c080 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2c090 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2c0a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2c0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c0c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2c0d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c0e0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2c0f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2c100 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2c110 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2c120 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2c130 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2c140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c150 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2c160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2c170 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2c180 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2c190 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2c1a0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2c1b0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2c1c0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2c1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c1e0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2c1f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c200 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2c210 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2c220 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2c230 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2c240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c250 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2c260 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2c270 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2c280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c290 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2c2a0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2c2b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c2c0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2c2d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c2e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2c2f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2c300 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2c310 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2c320 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2c330 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2c340 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2c350 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2c360 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2c370 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2c380 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2c390 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2c3a0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2c3b0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2c3c0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2c3d0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2c3e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2c3f0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2c400 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2c410 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2c420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c430 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2c440 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2c450 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2c460 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2c470 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2c480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2c490 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2c4a0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2c4b0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2c4c0 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2c4d0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2c4e0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2c4f0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2c500 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2c510 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2c520 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2c530 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2c540 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2c550 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2c560 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2c570 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2c580 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2c590 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
2c5a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2c5b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c5c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2c5d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2c5e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2c5f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c600 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2c610 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2c620 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c640 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c650 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2c660 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
2c670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2c680 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2c690 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2c6a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2c6b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2c6c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c6d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2c6e0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
2c6f0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2c700 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2c710 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c720 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2c730 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2c740 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2c750 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2c760 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c770 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2c780 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c790 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
2c7a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c7b0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c7c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c7d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2c7e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c7f0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2c800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2c810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c820 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2c830 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2c840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2c850 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2c860 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2c870 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2c880 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c890 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2c8a0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2c8b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c8c0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2c8d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2c8e0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2c8f0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2c900 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2c910 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2c920 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2c930 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2c940 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2c950 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2c960 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2c970 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c980 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2c990 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2c9a0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2c9b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2c9c0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2c9d0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c9e0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2c9f0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2ca00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ca10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2ca20 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2ca30 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2ca40 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2ca50 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2ca60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ca70 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2ca80 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2ca90 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2caa0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2cab0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2cac0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cad0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2cae0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2caf0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2cb00 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2cb10 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2cb20 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2cb30 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2cb40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2cb50 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2cb60 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2cb70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2cb80 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2cb90 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2cba0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2cbb0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2cbc0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2cbd0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2cbe0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2cbf0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2cc00 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2cc10 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2cc20 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2cc30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc40 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2cc50 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2cc60 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2cc70 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2cc80 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2cc90 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2cca0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2ccb0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2ccc0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2ccd0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2cce0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2ccf0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
2cd00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2cd10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2cd20 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2cd30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cd40 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2cd50 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2cd60 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2cd70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2cd80 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2cd90 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2cda0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cdb0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2cdc0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2cdd0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2cde0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2cdf0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2ce00 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2ce10 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2ce20 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2ce30 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2ce40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2ce50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ce60 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2ce70 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2ce80 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2ce90 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2cea0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2ceb0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2cec0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2ced0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2cee0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2cef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2cf00 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2cf10 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2cf20 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2cf30 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2cf40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2cf50 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2cf60 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2cf70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2cf80 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2cf90 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2cfa0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2cfb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cfc0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2cfd0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2cfe0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2cff0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2d000 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2d010 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2d020 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d030 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d040 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2d050 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2d060 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2d070 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2d080 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2d090 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d0a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2d0b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2d0c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2d0d0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2d0e0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2d0f0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2d100 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2d110 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2d120 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2d130 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d140 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
2d150 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d160 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2d170 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2d190 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2d1a0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2d1b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2d1c0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2d1d0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2d1e0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d1f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d200 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2d210 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d220 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d230 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2d240 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2d250 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2d260 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2d270 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d280 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2d290 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2d2a0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2d2b0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2d2c0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2d2d0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2d2e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d2f0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2d300 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2d310 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2d320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2d330 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2d340 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2d350 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2d360 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2d370 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2d380 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2d390 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2d3a0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2d3b0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2d3c0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2d3d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d3e0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2d3f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2d400 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2d410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d420 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2d430 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2d440 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2d450 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2d460 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2d470 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2d480 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2d490 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2d4a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d4b0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2d4c0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2d4d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d4e0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2d4f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2d500 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2d510 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2d520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2d530 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2d540 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2d550 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2d560 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2d570 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2d580 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2d590 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2d5a0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2d5b0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2d5c0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2d5d0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2d5e0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2d5f0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2d600 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2d610 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2d620 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2d630 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2d640 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2d650 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2d660 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2d670 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2d680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2d690 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2d6a0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2d6b0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2d6c0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2d6d0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2d6e0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2d6f0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2d700 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2d710 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d720 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2d730 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2d740 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2d750 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2d760 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2d770 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2d780 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2d790 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2d7a0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2d7b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2d7c0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2d7d0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2d7e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d7f0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2d800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2d810 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2d820 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2d830 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2d840 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2d850 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2d860 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2d870 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2d880 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2d890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2d8a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2d8b0 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2d8c0 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2d8d0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2d8e0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2d8f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d900 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2d910 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2d920 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2d930 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2d940 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2d950 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2d960 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d970 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2d980 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d990 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2d9a0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2d9b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2d9c0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2d9d0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2d9e0 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2d9f0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2da00 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2da10 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2da20 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2da30 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2da40 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2da50 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2da60 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2da70 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2da80 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2da90 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2daa0 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2dab0 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2dac0 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2dad0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2dae0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2daf0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2db00 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2db10 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2db20 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2db30 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2db40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2db50 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2db60 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2db70 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2db80 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2db90 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2dba0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2dbb0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2dbc0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2dbd0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2dbe0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2dbf0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2dc00 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2dc10 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2dc20 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2dc30 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2dc40 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2dc50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2dc60 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2dc70 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2dc80 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2dc90 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2dca0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2dcb0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2dcc0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2dcd0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2dce0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2dcf0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2dd00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dd10 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2dd20 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2dd30 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2dd40 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2dd50 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2dd60 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2dd70 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2dd80 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2dd90 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2dda0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2ddb0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2ddc0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2ddd0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2dde0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2ddf0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2de00 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2de10 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2de20 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2de30 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2de40 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2de50 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2de60 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2de70 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2de80 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2de90 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2dea0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2deb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dec0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2ded0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2dee0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2def0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2df00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2df10 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2df20 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2df30 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2df40 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2df50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2df60 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2df70 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2df80 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2df90 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2dfa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2dfb0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2dfc0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2dfd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2dfe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dff0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2e000 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2e010 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2e020 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e030 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e040 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2e050 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2e060 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2e070 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2e080 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2e090 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2e0a0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2e0b0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2e0c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2e0d0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2e0e0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2e0f0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2e100 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2e110 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2e120 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2e130 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2e140 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2e150 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2e160 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2e170 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2e180 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e190 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e1a0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2e1b0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2e1c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e1d0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e1e0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e1f0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e200 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e210 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e220 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e230 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e240 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e250 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2e260 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2e270 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2e280 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2e290 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2e2a0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2e2b0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e2c0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2e2d0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2e2e0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2e2f0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2e300 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2e310 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2e320 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2e330 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2e340 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2e350 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2e360 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e370 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2e380 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2e390 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2e3a0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2e3b0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2e3c0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2e3d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e3e0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2e3f0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2e400 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2e410 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2e420 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2e430 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2e440 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e450 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e460 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2e470 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2e480 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e490 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e4a0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e4b0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e4c0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e4d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e4f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e500 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e510 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e520 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e530 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e540 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
2e550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e570 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2e580 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2e590 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2e5a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2e5b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e5c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e5d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e5e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e5f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e600 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e610 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2e620 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e630 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e640 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2e650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2e660 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e670 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e680 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
2e690 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2e6a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2e6b0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2e6c0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2e6d0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2e6e0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2e6f0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2e700 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e710 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e720 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2e730 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e750 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2e760 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2e770 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
2e780 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2e790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e7a0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2e7b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2e7c0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2e7d0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2e7e0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2e7f0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2e800 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2e810 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2e820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e830 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2e840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e850 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2e860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e870 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2e880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e890 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2e8a0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2e8b0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2e8c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2e8d0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2e8e0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2e8f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2e900 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2e910 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2e920 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2e930 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e940 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2e950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e960 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
2e970 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
2e980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2e990 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
2e9a0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
2e9b0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2e9c0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2e9d0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2e9e0 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
2e9f0 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
2ea00 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
2ea10 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
2ea20 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
2ea30 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
2ea40 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2ea50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2ea60 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2ea70 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2ea80 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2ea90 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2eaa0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2eab0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
2eac0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
2ead0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
2eae0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
2eaf0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2eb00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2eb10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2eb20 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2eb30 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
2eb40 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2eb50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2eb60 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2eb70 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
2eb80 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2eb90 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2eba0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2ebb0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2ebc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2ebd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2ebe0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ebf0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2ec00 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2ec10 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ec20 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2ec30 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2ec40 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2ec50 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ec60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ec70 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2ec80 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2ec90 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2eca0 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2ecb0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
2ecc0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2ecd0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2ece0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2ecf0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
2ed00 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
2ed10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ed20 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
2ed30 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ed40 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
2ed50 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
2ed60 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
2ed70 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
2ed80 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
2ed90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2eda0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
2edb0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
2edc0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
2edd0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
2ede0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
2edf0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
2ee00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ee10 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2ee20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ee30 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
2ee40 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
2ee50 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2ee60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ee70 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
2ee80 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2ee90 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
2eea0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
2eeb0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
2eec0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
2eed0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2eee0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
2eef0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
2ef00 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
2ef10 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
2ef20 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2ef30 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
2ef40 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
2ef50 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
2ef60 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
2ef70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ef80 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
2ef90 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2efa0 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
2efb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2efc0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
2efd0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
2efe0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
2eff0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
2f000 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f010 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
2f020 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
2f030 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
2f040 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2f050 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
2f060 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2f070 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
2f080 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
2f090 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
2f0a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
2f0b0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
2f0c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f0d0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
2f0e0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
2f0f0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
2f100 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
2f110 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
2f120 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
2f130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2f140 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2f150 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2f160 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2f170 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2f180 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2f190 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2f1a0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2f1b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2f1c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2f1d0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2f1e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2f1f0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
2f200 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
2f210 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
2f220 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
2f230 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
2f240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2f250 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2f260 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2f270 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2f280 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2f290 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2f2a0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2f2b0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2f2c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2f2d0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2f2e0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2f2f0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2f300 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2f310 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2f320 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2f330 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2f340 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
2f350 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2f360 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2f370 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2f380 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2f390 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
2f3a0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
2f3b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2f3c0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
2f3d0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2f3e0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2f3f0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2f400 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
2f410 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
2f420 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
2f430 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
2f440 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
2f450 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2f460 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
2f470 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f480 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2f490 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f4a0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2f4b0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2f4c0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2f4d0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f4e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2f4f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f500 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2f510 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f520 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2f530 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2f540 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2f550 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2f560 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2f570 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2f580 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f590 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2f5a0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2f5b0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2f5c0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2f5d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2f5e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2f5f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f600 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f620 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2f630 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f640 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f650 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2f660 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2f670 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2f680 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2f690 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2f6b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f6c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f6d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f6e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f6f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f700 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f710 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f720 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2f730 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2f740 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2f750 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2f760 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2f770 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f780 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2f790 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2f7a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f7b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f7c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f7d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f7e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f7f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2f800 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f810 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f830 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2f840 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f850 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f860 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2f870 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f890 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2f8a0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2f8b0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2f8c0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2f8d0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2f8e0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2f8f0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2f900 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2f910 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2f920 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2f930 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2f940 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f950 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2f960 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2f970 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2f980 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2f990 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2f9a0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2f9b0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2f9c0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2f9d0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f9e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2f9f0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2fa00 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2fa10 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2fa20 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2fa30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2fa40 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2fa50 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2fa60 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2fa70 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2fa80 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2fa90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2faa0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2fab0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2fac0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2fad0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2fae0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2faf0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2fb00 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2fb10 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2fb20 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2fb30 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2fb40 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2fb50 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2fb60 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2fb70 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2fb80 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2fb90 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2fba0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2fbb0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2fbc0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2fbd0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2fbe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fbf0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2fc00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2fc10 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2fc20 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2fc30 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2fc40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2fc50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2fc60 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2fc70 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2fc80 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2fc90 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2fca0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2fcb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2fcc0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2fcd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2fce0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2fcf0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2fd00 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fd10 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2fd20 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2fd30 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2fd40 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2fd50 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2fd60 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2fd70 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2fd80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2fd90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fda0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2fdb0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2fdc0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2fdd0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2fde0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2fdf0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2fe00 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2fe10 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2fe20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2fe30 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2fe40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fe50 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2fe60 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2fe70 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2fe80 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2fe90 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2fea0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2feb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2fec0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2fed0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2fee0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2fef0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2ff00 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2ff10 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2ff20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2ff30 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2ff40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2ff50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2ff60 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2ff70 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2ff80 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2ff90 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2ffa0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ffb0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2ffc0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
2ffd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ffe0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2fff0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
30000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30010 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
30020 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
30030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
30040 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
30050 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
30060 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
30070 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
30080 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
30090 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
300a0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
300b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
300c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
300d0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
300e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
300f0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
30100 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
30110 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
30120 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
30130 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
30140 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
30150 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
30160 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
30170 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
30180 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30190 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
301a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
301b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
301c0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
301d0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
301e0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
301f0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
30200 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
30210 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
30220 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
30230 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
30240 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30250 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
30260 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
30270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30280 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
30290 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
302a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
302b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
302c0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
302d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
302e0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
302f0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
30300 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
30310 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
30320 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
30330 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
30340 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
30350 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
30360 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30370 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30380 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
30390 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
303a0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
303b0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
303c0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
303d0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
303e0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
303f0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
30400 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
30410 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
30420 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
30430 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
30440 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
30450 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
30460 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
30470 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
30480 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
30490 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
304a0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
304b0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
304c0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
304d0 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
304e0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
304f0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
30500 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
30510 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
30520 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
30530 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
30540 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
30550 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
30560 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
30570 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
30580 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
30590 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
305a0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
305b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
305c0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
305d0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
305e0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
305f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
30600 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
30610 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
30620 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
30630 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
30640 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
30650 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
30660 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
30670 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
30680 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
30690 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
306a0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
306b0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
306c0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
306d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
306e0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
306f0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
30700 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
30710 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30720 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
30730 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
30740 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
30750 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
30760 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
30770 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
30780 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
30790 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
307a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
307b0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
307c0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
307d0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
307e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
307f0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30800 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
30810 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
30820 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
30830 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
30840 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
30850 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
30860 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
30870 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
30880 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
30890 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
308a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
308b0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
308c0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
308d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
308e0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
308f0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
30900 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
30910 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
30920 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
30930 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
30940 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
30950 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
30960 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
30970 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
30980 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
30990 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
309a0 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
309b0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
309c0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
309d0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
309e0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
309f0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
30a00 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
30a10 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
30a20 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
30a30 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
30a40 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
30a50 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
30a60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
30a70 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
30a80 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
30a90 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
30aa0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
30ab0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
30ac0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
30ad0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
30ae0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
30af0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
30b00 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
30b10 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
30b20 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
30b30 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
30b40 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
30b50 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
30b60 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
30b70 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
30b80 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
30b90 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
30ba0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30bb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30bc0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30bd0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
30be0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
30bf0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
30c00 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
30c10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
30c20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30c30 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
30c40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
30c50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
30c60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30c70 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
30c80 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
30c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ca0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
30cb0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
30cc0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
30cd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30ce0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
30cf0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
30d00 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30d10 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
30d20 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
30d30 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
30d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30d50 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
30d60 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
30d70 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
30d80 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
30d90 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
30da0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
30db0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
30dc0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
30dd0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
30de0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
30df0 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
30e00 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
30e10 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
30e20 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
30e30 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
30e40 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
30e50 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
30e60 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
30e70 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
30e80 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
30e90 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
30ea0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
30eb0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
30ec0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
30ed0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
30ee0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
30ef0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
30f00 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
30f10 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
30f20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
30f30 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
30f40 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
30f50 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
30f60 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
30f70 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
30f80 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
30f90 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
30fa0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
30fb0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
30fc0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
30fd0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
30fe0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
30ff0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31000 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
31010 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
31020 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
31030 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
31040 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
31050 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
31060 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
31070 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
31080 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
31090 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
310a0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
310b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
310c0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
310d0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
310e0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
310f0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
31100 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
31110 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
31120 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
31130 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
31140 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
31150 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
31160 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
31170 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
31180 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
31190 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
311a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
311b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
311c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
311d0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
311e0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
311f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31200 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
31210 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
31220 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
31230 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
31240 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
31250 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
31260 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
31270 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
31280 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
31290 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
312a0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
312b0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
312c0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
312d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
312e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
312f0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
31300 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
31310 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
31320 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
31330 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
31340 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
31350 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
31360 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31370 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
31380 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
31390 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
313a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
313b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
313c0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
313d0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
313e0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
313f0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31410 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
31420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31430 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
31440 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
31450 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
31460 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
31470 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
31480 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
31490 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
314a0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
314b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
314c0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
314d0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
314e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
314f0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
31500 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
31510 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
31520 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
31530 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
31540 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
31550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31560 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
31570 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
31580 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
31590 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
315a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
315b0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
315c0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
315d0 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
315e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
315f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31600 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31610 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31620 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
31630 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31640 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
31650 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
31660 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
31670 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
31680 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
31690 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
316a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
316b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
316c0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
316d0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
316e0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
316f0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
31700 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
31710 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
31720 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
31730 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
31740 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
31750 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31760 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
31770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31780 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
31790 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
317a0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
317b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
317c0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
317d0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
317e0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
317f0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
31800 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
31810 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
31820 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
31830 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
31840 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31850 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
31860 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
31870 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
31880 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
31890 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
318a0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
318b0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
318c0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
318d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
318e0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
318f0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
31900 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
31910 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
31920 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31930 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
31940 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
31950 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
31960 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
31970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
31980 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
31990 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
319a0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
319b0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
319c0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
319d0 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
319e0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
319f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31a00 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
31a10 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31a20 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31a30 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
31a40 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
31a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31a60 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
31a70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31a80 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
31a90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31aa0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ac0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31ad0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31ae0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31af0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
31b00 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
31b10 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
31b20 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
31b30 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31b40 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31b50 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31b60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31b70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31b80 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
31b90 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31ba0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31bb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31bd0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
31be0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31bf0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31c00 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31c10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31c20 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
31c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31c40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31c50 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
31c60 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
31c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31c80 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
31c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ca0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
31cb0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
31cc0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
31cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ce0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31cf0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
31d00 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
31d10 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
31d20 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
31d30 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
31d40 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
31d50 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
31d60 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
31d70 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
31d80 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
31d90 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
31da0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
31db0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
31dc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31dd0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31de0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31df0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
31e00 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31e10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31e20 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31e30 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
31e40 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
31e50 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
31e60 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
31e70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
31e80 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
31e90 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
31ea0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
31eb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31ec0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ed0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31ee0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31ef0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31f00 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31f10 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
31f20 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
31f30 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
31f40 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
31f50 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
31f60 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
31f70 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
31f80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31f90 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
31fa0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
31fb0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
31fc0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
31fd0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
31fe0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
31ff0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
32000 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
32010 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
32020 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
32030 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
32040 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
32050 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
32060 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
32070 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
32080 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
32090 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
320a0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
320b0 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
320c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
320d0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
320e0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
320f0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
32100 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
32110 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
32120 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
32130 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32140 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
32150 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
32160 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
32170 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
32180 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
32190 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
321a0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
321b0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
321c0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
321d0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
321e0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
321f0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
32200 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
32210 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
32220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32230 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32240 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
32250 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
32260 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
32270 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
32280 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
32290 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
322a0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
322b0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
322c0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
322d0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
322e0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
322f0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
32300 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
32310 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
32320 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
32330 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
32340 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
32350 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
32360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
32370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32380 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32390 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
323a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
323b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
323c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
323d0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
323e0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
323f0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
32400 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
32410 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
32420 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
32430 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
32440 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
32450 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
32460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32470 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
32480 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
32490 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
324a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
324b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
324c0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
324d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
324e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
324f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
32500 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
32510 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
32520 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
32530 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
32540 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
32550 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
32560 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
32570 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
32580 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
32590 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
325a0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
325b0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
325c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
325d0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
325e0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
325f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32600 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32610 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
32620 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
32630 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32650 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
32660 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
32670 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
32680 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
32690 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
326a0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
326b0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
326c0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
326d0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
326e0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
326f0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
32700 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
32710 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32720 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
32730 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
32740 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
32750 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
32760 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
32770 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
32780 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
32790 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
327a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
327b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
327c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
327d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
327e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
327f0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
32800 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
32810 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
32820 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32830 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
32840 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32850 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53  t char*, int);.S
32860 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32880 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
32890 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
328a0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
328b0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
328c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
328d0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
328e0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
328f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
32910 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
32920 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
32930 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32940 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32950 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32960 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
32970 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32980 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
32990 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
329a0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
329b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
329c0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
329d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
329e0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
329f0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32a00 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
32a10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32a20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32a30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32a40 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
32a50 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
32a60 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
32a70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32a80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32a90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32aa0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
32ab0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
32ac0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
32ad0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
32ae0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
32af0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
32b00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32b10 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32b20 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
32b30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32b40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32b50 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
32b60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32b70 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
32b80 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
32b90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
32ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
32bb0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
32bc0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
32bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
32be0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
32bf0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
32c00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32c10 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
32c20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
32c30 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
32c40 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
32c50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32c60 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
32c70 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
32c80 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
32c90 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
32ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32cb0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
32cc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32cd0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
32ce0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
32cf0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
32d00 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
32d10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32d20 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
32d30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32d40 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
32d50 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32d60 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
32d70 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
32d80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32d90 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
32da0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
32db0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
32dc0 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
32dd0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
32de0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
32df0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
32e00 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
32e10 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
32e20 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
32e30 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
32e40 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
32e50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
32e60 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
32e70 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
32e80 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
32e90 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
32ea0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
32eb0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
32ec0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
32ed0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
32ee0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
32ef0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
32f00 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
32f10 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
32f20 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
32f30 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
32f40 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
32f50 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
32f60 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
32f70 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
32f80 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
32f90 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
32fa0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
32fb0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
32fc0 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
32fd0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
32fe0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32ff0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
33000 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
33010 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
33020 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
33030 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
33040 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
33050 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
33060 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
33070 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
33080 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
33090 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
330a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
330b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
330c0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
330d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
330e0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
330f0 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
33100 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
33110 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
33120 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
33130 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
33140 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
33150 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
33160 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
33170 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
33180 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
33190 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
331a0 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
331b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
331c0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
331d0 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
331e0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
331f0 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
33200 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
33210 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
33220 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33230 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
33240 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
33250 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
33260 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
33270 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
33280 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
33290 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
332a0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
332b0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
332c0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
332d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
332e0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
332f0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
33300 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
33310 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
33320 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
33330 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
33340 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
33350 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
33360 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33370 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
33380 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
33390 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
333a0 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
333b0 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
333c0 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
333d0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
333e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
333f0 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
33400 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
33410 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33420 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
33430 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
33440 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
33450 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
33460 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
33470 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33480 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
33490 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
334a0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
334b0 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
334c0 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
334d0 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
334e0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
334f0 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
33500 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
33510 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
33520 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
33530 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
33540 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
33550 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
33560 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
33570 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
33580 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
33590 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
335a0 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
335b0 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
335c0 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
335d0 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
335e0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
335f0 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
33600 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
33610 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
33620 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
33630 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
33640 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
33650 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
33660 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
33670 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
33680 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
33690 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
336a0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
336b0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
336c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
336d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
336e0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
336f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
33700 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
33710 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
33720 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
33730 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33740 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
33750 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
33760 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33770 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
33780 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
33790 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
337a0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
337b0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
337c0 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
337d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
337e0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
337f0 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
33800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33810 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
33820 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
33830 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
33840 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
33850 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
33860 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
33870 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
33880 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33890 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
338a0 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
338b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
338c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
338d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
338e0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
338f0 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
33900 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
33910 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
33920 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
33930 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33940 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
33950 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
33960 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
33970 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
33980 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
33990 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
339a0 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
339b0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
339c0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
339d0 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
339e0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
339f0 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
33a00 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
33a10 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
33a20 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
33a30 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
33a40 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
33a50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
33a60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33a70 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33a80 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  6()]..*/.SQLITE_
33a90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33aa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33ab0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33ac0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33ad0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
33ae0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
33af0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
33b00 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
33b10 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
33b20 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53  onst void*).);.S
33b30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33b40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33b50 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
33b60 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
33b70 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
33b80 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
33b90 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
33ba0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33bb0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33bc0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33bd0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
33be0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33bf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33c00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33c10 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
33c20 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
33c30 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
33c40 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
33c50 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
33c60 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
33c70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33c80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33c90 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
33ca0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
33cb0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
33cc0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
33cd0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
33ce0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
33cf0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
33d00 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
33d10 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
33d20 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
33d30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
33d40 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
33d50 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
33d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33d70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
33d80 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
33d90 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
33da0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
33db0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
33dc0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
33dd0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
33de0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
33df0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
33e00 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
33e10 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
33e20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
33e30 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
33e40 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
33e50 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
33e60 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
33e70 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33e80 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
33e90 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
33ea0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
33eb0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
33ec0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
33ed0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
33ee0 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
33ef0 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
33f00 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
33f10 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
33f20 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
33f30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
33f40 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
33f50 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
33f60 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
33f70 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
33f80 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
33f90 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
33fa0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
33fb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33fc0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
33fd0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
33fe0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
33ff0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
34000 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
34010 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34020 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
34030 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
34040 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34050 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
34060 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
34070 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
34080 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
34090 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
340a0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
340b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
340c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
340d0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
340e0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
340f0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
34100 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
34110 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34120 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34130 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34140 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34150 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
34160 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34170 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
34180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34190 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
341a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
341b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
341c0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
341d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
341e0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
341f0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34200 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
34210 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  ar*).);.SQLITE_A
34220 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
34230 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34240 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
34250 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
34260 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
34270 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
34280 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
34290 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
342a0 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
342b0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
342c0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
342d0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
342e0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
342f0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
34300 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
34310 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
34320 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
34330 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
34340 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
34350 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
34360 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
34370 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34380 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
34390 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
343a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
343b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
343c0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
343d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
343e0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
343f0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
34400 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
34410 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
34420 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
34430 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
34440 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
34450 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
34460 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
34470 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
34480 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
34490 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
344a0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
344b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
344c0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
344d0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
344e0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
344f0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
34500 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
34510 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34520 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
34530 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34540 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34550 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34560 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34570 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34580 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
34590 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
345a0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
345b0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
345c0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
345d0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
345e0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
345f0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
34600 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
34610 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34620 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
34630 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
34640 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
34650 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
34660 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
34670 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
34680 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
34690 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
346a0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
346b0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
346c0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
346d0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
346e0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
346f0 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
34700 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49  ll work..*/.SQLI
34710 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
34720 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
34730 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
34740 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
34750 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
34760 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
34770 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
34780 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
34790 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
347a0 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
347b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
347c0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
347d0 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
347e0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
347f0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
34800 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
34810 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
34820 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
34830 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
34840 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
34850 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
34860 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
34870 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
34880 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
34890 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
348a0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
348b0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
348c0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
348d0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
348e0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
348f0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
34900 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
34910 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
34920 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
34930 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
34940 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
34950 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
34960 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
34970 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
34980 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
34990 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
349a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
349b0 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
349c0 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
349d0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
349e0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
349f0 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
34a00 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
34a10 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
34a20 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
34a30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
34a40 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
34a50 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
34a60 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
34a70 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
34a80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34a90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
34aa0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
34ab0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
34ac0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
34ad0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
34ae0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
34af0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
34b00 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
34b10 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
34b20 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
34b30 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
34b40 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
34b50 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
34b60 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
34b70 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
34b80 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
34b90 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
34ba0 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
34bb0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
34bc0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
34bd0 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
34be0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
34bf0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
34c00 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
34c10 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
34c20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
34c30 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
34c40 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
34c50 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
34c60 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
34c70 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
34c80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
34c90 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
34ca0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
34cb0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
34cc0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
34cd0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
34ce0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34cf0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
34d00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
34d10 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
34d20 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
34d30 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
34d40 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
34d50 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
34d60 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
34d70 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
34d80 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
34d90 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
34da0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
34db0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
34dc0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
34dd0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
34de0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
34df0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
34e00 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
34e10 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
34e20 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
34e30 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
34e40 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
34e50 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
34e60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
34e70 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
34e80 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
34e90 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
34ea0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
34eb0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
34ec0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
34ed0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34ee0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
34ef0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
34f00 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
34f10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34f20 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
34f30 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
34f40 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
34f50 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
34f60 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
34f70 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
34f80 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
34f90 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
34fa0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
34fb0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
34fc0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
34fd0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
34fe0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
34ff0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
35000 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
35010 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35020 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
35030 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
35040 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
35050 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
35060 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
35070 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
35080 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
35090 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
350a0 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46  lding Database F
350b0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
350c0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
350d0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
350e0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
350f0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
35100 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
35110 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
35120 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
35130 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a  database files.*
35140 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68  * specified with
35150 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
35160 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64  name and created
35170 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a   or accessed by.
35180 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  ** SQLite when u
35190 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
351a0 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33  windows [sqlite3
351b0 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c  _vfs | VFS] will
351c0 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74   be assumed.** t
351d0 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f  o be relative to
351e0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
351f0 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  )^ ^If this vari
35200 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a  able is a NULL.*
35210 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  * pointer, then 
35220 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
35230 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hat all database
35240 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64   files specified
35250 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74  .** with a relat
35260 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65  ive pathname are
35270 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65   relative to the
35280 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
35290 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72  ry.** for the pr
352a0 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65  ocess.  Only the
352b0 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b   windows VFS mak
352c0 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67  es use of this g
352d0 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c  lobal.** variabl
352e0 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64  e; it is ignored
352f0 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53   by the unix VFS
35300 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67  ..**.** Changing
35310 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35320 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c  is variable whil
35330 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
35340 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70  nection is.** op
35350 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  en can result in
35360 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62   a corrupt datab
35370 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ase..**.** It is
35380 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35390 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
353a0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
353b0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
353c0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
353d0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
353e0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
353f0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
35400 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
35410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
35420 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
35430 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
35440 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
35450 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
35460 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
35470 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35480 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35490 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
354a0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
354b0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
354c0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
354d0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
354e0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
354f0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35500 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
35510 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
35520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61  **.** ^The [data
35530 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35540 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
35550 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
35560 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
35570 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
35580 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35590 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
355a0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
355b0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61  re,.** the [data
355c0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
355d0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
355e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
355f0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
35600 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
35610 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
35620 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
35630 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
35640 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
35650 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
35660 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
35670 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
35680 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
35690 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
356a0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
356b0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
356c0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
356d0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
356e0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
356f0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
35700 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
35710 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
35720 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
35730 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
35740 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35750 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
35760 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
35770 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
35780 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
35790 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63  lite3_data_direc
357a0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
357b0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
357c0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
357d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
357e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
357f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35800 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
35810 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
35820 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
35830 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
35840 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
35850 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
35860 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
35870 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
35880 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
35890 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
358a0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
358b0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
358c0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
358d0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
358e0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
358f0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35900 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35910 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35920 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
35930 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
35940 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
35950 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
35960 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
35970 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
35980 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
35990 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
359a0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
359b0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
359c0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
359d0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
359e0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
359f0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35a00 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35a10 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
35a20 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
35a30 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
35a40 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
35a50 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
35a60 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
35a70 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
35a80 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
35a90 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
35aa0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
35ab0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
35ac0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
35ad0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
35ae0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
35af0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
35b00 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
35b10 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
35b20 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
35b30 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
35b40 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
35b50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35b60 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
35b70 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
35b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
35b90 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
35ba0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
35bb0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
35bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35bd0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
35be0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
35bf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35c00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
35c10 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
35c20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35c30 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
35c40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35c50 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
35c60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
35c70 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
35c80 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
35c90 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
35ca0 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
35cb0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
35cc0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
35cd0 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
35ce0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
35cf0 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
35d00 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
35d10 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
35d20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
35d30 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
35d40 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
35d50 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
35d60 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
35d70 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68  I3REF: Return Th
35d80 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41  e Filename For A
35d90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
35da0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
35db0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
35dc0 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61  ame(D,N) interfa
35dd0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
35de0 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61  nter to a filena
35df0 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  me.** associated
35e00 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e   with database N
35e10 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
35e20 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74  .  ^The main dat
35e30 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61  abase file.** ha
35e40 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e  s the name "main
35e50 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ".  If there is 
35e60 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61  no attached data
35e70 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61  base N on the da
35e80 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
35e90 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61  tion D, or if da
35ea0 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65  tabase N is a te
35eb0 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65  mporary or in-me
35ec0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74  mory database, t
35ed0 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  hen.** a NULL po
35ee0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
35ef0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
35f00 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20  lename returned 
35f10 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
35f20 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f   is the output o
35f30 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61  f the.** xFullPa
35f40 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66  thname method of
35f50 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e   the [VFS].  ^In
35f60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
35f70 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69  e filename.** wi
35f80 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74  ll be an absolut
35f90 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e  e pathname, even
35fa0 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   if the filename
35fb0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e   used.** to open
35fc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
35fd0 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55  iginally was a U
35fe0 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70  RI or relative p
35ff0 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49  athname..*/.SQLI
36000 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
36010 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  r *sqlite3_db_fi
36020 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a  lename(sqlite3 *
36030 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
36040 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
36050 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
36060 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61  mine if a databa
36070 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a  se is read-only.
36080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36090 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44  e3_db_readonly(D
360a0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
360b0 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64  turns 1 if the d
360c0 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20  atabase N.** of 
360d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20  connection D is 
360e0 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20  read-only, 0 if 
360f0 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 65  it is read/write
36100 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20  , or -1 if N is 
36110 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  not.** the name 
36120 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  of a database on
36130 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
36140 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36150 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
36160 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62  only(sqlite3 *db
36170 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
36180 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  bName);../*.** C
36190 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
361a0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
361b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
361c0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
361d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
361e0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
361f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36200 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
36210 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
36220 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
36230 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
36240 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e    ^If pStmt is N
36250 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
36260 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36270 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
36280 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
36290 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
362a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
362b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
362c0 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49  nection pDb.  ^I
362d0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
362e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
362f0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
36300 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
36310 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
36320 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
36330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36340 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
36350 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
36360 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
36370 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
36380 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
36390 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
363a0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
363b0 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
363c0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
363d0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
363e0 49 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  I sqlite3_stmt *
363f0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
36400 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
36410 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36420 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36430 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
36440 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
36450 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
36460 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
36470 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36480 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
36490 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
364a0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
364b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
364c0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
364d0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
364e0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
364f0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
36500 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
36510 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
36520 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
36530 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
36540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36550 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
36560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36570 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
36580 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36590 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
365a0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
365b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
365c0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
365d0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
365e0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
365f0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
36600 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
36610 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36620 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
36630 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36640 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36650 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
36660 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
36670 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
36680 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36690 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
366a0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
366b0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
366c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
366d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
366e0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
366f0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
36700 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
36710 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36720 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
36730 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
36740 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
36750 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
36760 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
36770 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
36780 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
36790 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
367a0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
367b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
367c0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
367d0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
367e0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
367f0 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
36800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
36810 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
36820 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
36830 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
36840 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
36850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36860 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
36870 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
36880 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
36890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
368a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
368b0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
368c0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
368d0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
368e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
368f0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
36900 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
36910 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
36920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
36930 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
36940 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
36950 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
36960 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
36970 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
36980 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67  ote that running
36990 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73   any other SQL s
369a0 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75  tatements, inclu
369b0 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74  ding SELECT stat
369c0 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65  ements,.** or me
369d0 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  rely calling [sq
369e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
369f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36a00 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f  _step()] will mo
36a10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
36a20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36a30 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
36a40 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
36a50 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
36a60 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
36a70 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
36a80 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
36a90 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
36aa0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
36ab0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
36ac0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
36ad0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
36ae0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
36af0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
36b00 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
36b10 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
36b20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
36b30 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
36b40 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
36b50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
36b60 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
36b70 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
36b80 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
36b90 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
36ba0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
36bb0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
36bc0 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
36bd0 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
36be0 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
36bf0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
36c00 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
36c10 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
36c20 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
36c30 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
36c40 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
36c50 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
36c60 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
36c70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
36c80 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
36c90 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
36ca0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
36cb0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
36cc0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
36cd0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
36ce0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
36cf0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
36d00 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
36d10 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
36d20 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
36d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36d40 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
36d50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
36d60 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
36d70 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
36d80 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ace..*/.SQLITE_A
36d90 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
36da0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
36db0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
36dc0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  id*), void*);.SQ
36dd0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
36de0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36df0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
36e00 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
36e10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
36e20 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
36e30 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
36e40 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
36e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
36e60 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
36e70 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36e80 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
36e90 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
36ea0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36eb0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
36ec0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
36ed0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
36ee0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36ef0 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
36f00 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
36f10 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  deleted..** ^Any
36f20 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
36f30 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
36f40 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
36f50 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
36f60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36f70 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
36f80 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  den..**.** ^The 
36f90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
36fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
36fb0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
36fc0 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
36fd0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
36fe0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
36ff0 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  eted..** ^The fi
37000 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
37010 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
37020 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
37030 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
37040 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
37050 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68  e_hook()..** ^Th
37060 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
37070 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
37080 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
37090 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
370a0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
370b0 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
370c0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
370d0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
370e0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
370f0 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
37100 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  ed..** ^The thir
37110 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37120 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37130 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
37140 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
37150 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
37160 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
37170 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
37180 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66  d row..** ^The f
37190 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
371a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
371b0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f  rowid] of the ro
371c0 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61  w..** ^In the ca
371d0 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
371e0 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
371f0 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
37200 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
37210 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75  e..**.** ^(The u
37220 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
37230 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
37240 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
37250 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
37260 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
37270 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
37280 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29  lite_sequence).)
37290 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ^.**.** ^In the 
372a0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
372b0 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61  tation, the upda
372c0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f  te hook.** is no
372d0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64  t invoked when d
372e0 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20  uplication rows 
372f0 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61  are deleted beca
37300 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e  use of an.** [ON
37310 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43   CONFLICT | ON C
37320 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d  ONFLICT REPLACE]
37330 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69   clause.  ^Nor i
37340 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
37350 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
37360 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
37370 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
37380 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
37390 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
373a0 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
373b0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
373c0 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
373d0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
373e0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
373f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
37400 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
37410 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
37420 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
37430 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
37440 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37450 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
37460 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
37470 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
37480 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
37490 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
374a0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
374b0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
374c0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
374d0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
374e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
374f0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
37500 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
37510 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
37520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37530 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
37540 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
37550 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
37560 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37570 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
37580 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
37590 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
375a0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  aph..**.** ^The 
375b0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
375c0 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
375d0 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ion.** returns t
375e0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
375f0 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
37600 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  call.** on the s
37610 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37620 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
37630 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
37640 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e  first call on D.
37650 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
37660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
37670 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
37680 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
37690 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
376a0 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49  erfaces..*/.SQLI
376b0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
376c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
376d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
376e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
376f0 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
37700 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
37710 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
37720 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
37730 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
37740 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
37750 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
37760 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
37770 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
37780 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
37790 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
377a0 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
377b0 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
377c0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
377d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
377e0 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
377f0 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
37800 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
37810 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
37820 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
37830 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
37840 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
37850 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
37860 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68  e.)^.**.** ^Cach
37870 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
37880 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
37890 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
378a0 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
378b0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
378c0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
378d0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
378e0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
378f0 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
37900 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
37910 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
37920 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
37930 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
37940 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
37950 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
37960 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
37970 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
37980 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
37990 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
379a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
379b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
379c0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
379d0 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
379e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
379f0 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
37a00 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
37a10 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
37a20 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
37a30 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e  y were opened.)^
37a40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
37a50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
37a60 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
37a70 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
37a80 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
37a90 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
37aa0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
37ab0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
37ac0 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a  otherwise.)^.**.
37ad0 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65  ** ^Shared cache
37ae0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37af0 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
37b00 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
37b10 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
37b20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
37b30 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
37b40 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
37b50 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
37b60 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
37b70 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
37b80 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
37b90 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
37ba0 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53  Cache Mode].*/.S
37bb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37bc0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
37bd0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
37be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37bf0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
37c00 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
37c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37c20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37c30 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
37c40 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
37c50 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
37c60 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
37c70 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
37c80 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
37c90 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
37ca0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
37cb0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
37cc0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
37cd0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
37ce0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
37cf0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
37d00 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
37d10 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
37d20 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
37d30 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
37d40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
37d50 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
37d60 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
37d70 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
37d80 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
37d90 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
37da0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37db0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
37dc0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
37dd0 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
37de0 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
37df0 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
37e00 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
37e10 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
37e20 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
37e30 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
37e40 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65  e3_db_release_me
37e50 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  mory()].*/.SQLIT
37e60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37e70 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
37e80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
37e90 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d  PI3REF: Free Mem
37ea0 6f 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61  ory Used By A Da
37eb0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
37ec0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
37ed0 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
37ee0 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66  memory(D) interf
37ef0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
37f00 66 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61  free as much hea
37f10 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70  p.** memory as p
37f20 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74  ossible from dat
37f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f40 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a   D. Unlike the.*
37f50 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
37f60 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74  se_memory()] int
37f70 65 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74  erface, this int
37f80 65 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74  erface is effect
37f90 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68   even.** when th
37fa0 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  en [SQLITE_ENABL
37fb0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
37fc0 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ENT] compile-tim
37fd0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f  e option is.** o
37fe0 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  mitted..**.** Se
37ff0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
38000 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38010 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
38020 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
38030 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73  release_memory(s
38040 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
38050 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
38060 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
38070 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
38080 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
38090 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
380a0 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
380b0 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
380c0 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
380d0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
380e0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
380f0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
38100 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
38110 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
38120 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
38130 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
38140 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
38150 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
38160 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
38170 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
38180 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
38190 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
381a0 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
381b0 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
381c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
381d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
381e0 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
381f0 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
38200 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
38210 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
38220 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
38230 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
38240 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
38250 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
38260 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
38270 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
38280 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38290 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
382a0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
382b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
382c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66  from sqlite3_sof
382d0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
382e0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a   is the size of.
382f0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
38300 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20   limit prior to 
38310 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67  the call, or neg
38320 61 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73  ative in the cas
38330 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  e of an.** error
38340 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  .  ^If the argum
38350 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76  ent N is negativ
38360 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61  e.** then no cha
38370 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74  nge is made to t
38380 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
38390 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  it.  Hence, the 
383a0 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20  current.** size 
383b0 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  of the soft heap
383c0 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65   limit can be de
383d0 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f  termined by invo
383e0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
383f0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
38400 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74  4() with a negat
38410 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ive argument..**
38420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
38430 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74  ment N is zero t
38440 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61  hen the soft hea
38450 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62  p limit is disab
38460 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  led..**.** ^(The
38470 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
38480 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64   is not enforced
38490 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
384a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
384b0 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  * if one or more
384c0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f   of following co
384d0 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75  nditions are tru
384e0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
384f0 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68   <li> The soft h
38500 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74  eap limit is set
38510 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69   to zero..** <li
38520 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  > Memory account
38530 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20  ing is disabled 
38540 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74  using a combinat
38550 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
38560 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
38570 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
38580 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e  IG_MEMSTATUS],..
38590 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70  .) start-time op
385a0 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
385b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46   the [SQLITE_DEF
385c0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20  AULT_MEMSTATUS] 
385d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
385e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20  ion..** <li> An 
385f0 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65  alternative page
38600 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
38610 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69  ation is specifi
38620 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
38630 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
38640 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
38650 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a  _PCACHE2],...)..
38660 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65  ** <li> The page
38670 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73   cache allocates
38680 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65   from its own me
38690 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69  mory pool suppli
386a0 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73  ed.**      by [s
386b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
386c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
386d0 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61  GECACHE],...) ra
386e0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
386f0 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e    from the heap.
38700 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
38710 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  * Beginning with
38720 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
38730 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20  3.7.3, the soft 
38740 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
38750 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64  forced.** regard
38760 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
38770 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
38780 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
38790 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20  _MANAGEMENT].** 
387a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
387b0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
387c0 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   With [SQLITE_EN
387d0 41