System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1545fa161adaa10108ab08da93419454bb395bad:


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 37 22 0a 23 64 65 66 69 6e 65 20 53 51  .7.7".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 37 30 30 37 0a 23 64 65 66  BER 3007007.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d  E_ID      "2011-
1070: 30 37 2d 31 32 20 31 34 3a 33 38 3a 32 35 20 30  07-12 14:38:25 0
1080: 32 30 37 66 64 39 62 30 63 30 66 36 62 61 61 33  207fd9b0c0f6baa3
1090: 63 32 63 62 38 62 61 35 38 38 61 64 35 38 35 35  c2cb8ba588ad5855
10a0: 30 37 38 34 38 62 33 22 0a 0a 2f 2a 0a 2a 2a 20  07848b3"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 6e 67  ompiled mutexing
1c70: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75   code omitted du
1c80: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e to the.** [SQL
1c90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ca0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1cb0: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f  ion being set to
1cc0: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65   0..**.** SQLite
1cd0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1ce0: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1cf0: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1d00: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
1d10: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
1d20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1d30: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
1d40: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
1d50: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
1d60: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1d70: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1d90: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1da0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1db0: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1dc0: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1dd0: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1de0: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1df0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1e00: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
1e10: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
1e20: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
1e30: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
1e40: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1e50: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1e60: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1e70: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1e80: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1e90: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1ea0: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1eb0: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1ec0: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1ed0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68   enabled..** ^Th
1ee0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1ef0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1f00: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
1f10: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f20: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f30: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74  d by an applicat
1f40: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ion to make sure
1f50: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1f60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1f70: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1f80: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1f90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1fa0: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1fb0: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1fc0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fd0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1fe0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1ff0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
2000: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
2010: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
2020: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
2030: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
2040: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2050: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
2060: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
2070: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78  or =2 then mutex
2080: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  es are enabled b
2090: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a  y default but.**
20a0: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72   can be fully or
20b0: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62   partially disab
20c0: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c  led using a call
20d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
20e0: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74  fig()].** with t
20f0: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45  he verbs [SQLITE
2100: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2110: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
2120: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2130: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  D],.** or [SQLIT
2140: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e  E_CONFIG_MUTEX].
2150: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
2160: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
2170: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2180: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
2190: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
21a0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
21b0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
21c0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
21d0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
21e0: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
21f0: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
2200: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
2210: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2220: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2230: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
2240: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
2250: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
2260: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
2270: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
2280: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
2290: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
22a0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
22b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
22c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
22d0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
22e0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
22f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2300: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2310: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
2320: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2330: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2340: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2350: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2360: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2370: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2380: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2390: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
23a0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
23b0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
23c0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
23d0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
23e0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
23f0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
2400: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
2410: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2420: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2430: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2440: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2450: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2460: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2470: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2480: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
2490: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
24a0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
24b0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
24c0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
24d0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
24e0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24f0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2510: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2520: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2530: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2540: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2550: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2570: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2580: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2590: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25a0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25b0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
25c0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
25d0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
25e0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
25f0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2600: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2610: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2620: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2630: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2640: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2650: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2660: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2670: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2680: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2690: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26a0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26b0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
26c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
26d0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
26e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
26f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2700: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2710: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2720: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2730: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2740: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2750: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2760: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2770: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2780: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2790: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27a0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27b0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27c0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
27d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
27e0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
27f0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2800: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2810: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2820: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2830: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2840: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2850: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2860: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
2870: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28a0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28b0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
28c0: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
28d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
28e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
28f0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2900: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2910: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2920: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2930: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2940: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2950: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
2960: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
2970: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
2980: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29a0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29b0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
29c0: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
29d0: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
29e0: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
29f0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a00: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a10: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a20: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a40: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a50: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2a60: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2a70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a80: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2a90: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2aa0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ab0: 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 6e  3_close() routin
2ac0: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2ad0: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2ae0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2af0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b00: 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 72  e3_close() retur
2b10: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  n SQLITE_OK if t
2b20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2b30: 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 73  ect is.** succes
2b40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2b50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2b60: 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 61 72  ted resources ar
2b70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
2b80: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2b90: 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 5f  s must [sqlite3_
2ba0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2bb0: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2bc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2bd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
2be0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2bf0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2c00: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
2c10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
2c20: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2c30: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2c40: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2c50: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2c60: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2c70: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2c80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c90: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2ca0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2cb0: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2cc0: 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c 4f 42  ements] or [BLOB
2cd0: 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 6e 20   handles], then 
2ce0: 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  it returns.** SQ
2cf0: 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a  LITE_BUSY..**.**
2d00: 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c   ^If [sqlite3_cl
2d10: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
2d20: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
2d30: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
2d40: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
2d50: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
2d60: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
2d70: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
2d80: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d90: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74  3_close(C)] must
2da0: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
2db0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
2dc0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2dd0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
2de0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
2df0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2e00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e10: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2e30: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
2e40: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
2e50: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
2e60: 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  se() with a NULL
2e70: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
2e80: 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 6d 6c  t is a .** harml
2e90: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
2ea0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2eb0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
2ec0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
2ed0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
2ee0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
2ef0: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
2f00: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
2f10: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
2f20: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
2f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2f40: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
2f50: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
2f60: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
2f70: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
2f80: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
2f90: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
2fa0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
2fb0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
2fc0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
2fd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2fe0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2ff0: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3000: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3010: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3020: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3030: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3040: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3050: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
3060: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
3070: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
3080: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
3090: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
30a0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
30b0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
30c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30d0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
30e0: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
30f0: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3100: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3110: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3120: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3130: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
3140: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
3150: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
3160: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3170: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
3180: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
3190: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
31a0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31b0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
31c0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
31d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
31e0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
31f0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3200: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3210: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3220: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
3240: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3250: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3260: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
3270: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
3280: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3290: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
32a0: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
32b0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
32c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
32e0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
32f0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3300: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3310: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3320: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3330: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3340: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3350: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3360: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3370: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3380: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3390: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
33a0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
33b0: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
33c0: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
33d0: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
33e0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
33f0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3400: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3410: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3420: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3430: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3440: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3450: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3460: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3470: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3480: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3490: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
34a0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
34b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
34c0: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
34d0: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
34e0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
34f0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3500: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3510: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3520: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3530: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3540: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3550: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3560: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3570: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3580: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3590: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
35a0: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
35b0: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
35c0: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
35d0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
35e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
35f0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3600: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3610: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3620: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3630: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3640: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3650: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3660: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3670: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3680: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3690: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
36a0: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
36b0: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
36c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
36d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
36e0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3700: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3710: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3720: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3730: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3740: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3750: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3760: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3770: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3780: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3790: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
37a0: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
37b0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
37c0: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
37d0: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
37e0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
37f0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3800: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3810: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3820: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3830: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3840: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3850: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3860: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3870: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3880: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3890: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
38a0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
38b0: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
38c0: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
38d0: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
38e0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
38f0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3900: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3910: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3920: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3930: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3940: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3950: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3960: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3970: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3980: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3990: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
39a0: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
39b0: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
39c0: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
39d0: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
39e0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
39f0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3a00: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3a10: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3a20: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3a30: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3a40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3a50: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3a60: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3a90: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3aa0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3ab0: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3ac0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3ad0: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3ae0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3af0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3b00: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3b10: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3b20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3b30: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3b40: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3b50: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3b60: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3b70: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3b80: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3b90: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3ba0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3bb0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3bc0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3bd0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3be0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3bf0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
3c00: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3c10: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3c40: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3c50: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
3c60: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
3c90: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
3ca0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3cb0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3cc0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3cd0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
3ce0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3d10: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
3d20: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
3d30: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3d60: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3d70: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3d80: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3d90: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
3da0: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
3db0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
3dc0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
3dd0: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
3de0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
3df0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
3e00: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
3e10: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
3e20: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
3e30: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
3e40: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
3e50: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
3e60: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3e70: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3e80: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3e90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3eb0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3ec0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3ed0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3ee0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3f00: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3f10: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3f20: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3f30: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3f40: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3f50: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3f60: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3f70: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3f80: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3fa0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3fb0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3fc0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3ff0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
4000: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
4010: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
4020: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
4030: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4040: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4050: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4060: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
4070: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
4080: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
4090: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
40a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
40b0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
40c0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
40d0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
40e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40f0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4100: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4110: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4120: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4130: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4140: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4150: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4170: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
4180: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
4190: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
41a0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
41b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
41c0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
41d0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
41e0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
41f0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4210: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4220: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4230: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4240: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4250: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4260: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
4270: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
4280: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
42b0: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
42c0: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
42d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
42e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4300: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4310: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4320: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4340: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
4350: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4360: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4370: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4380: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4390: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
43a0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
43b0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
43d0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
43e0: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4410: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4420: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4430: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4440: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4450: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4460: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
4470: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
4480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
4490: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
44a0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
44b0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
44c0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
44d0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
44e0: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
44f0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4510: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4520: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4530: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4550: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4560: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
4570: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
4580: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
45a0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
45b0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
45e0: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
45f0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4600: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4620: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4630: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4640: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
4650: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
4660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
4670: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
4680: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
4690: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
46a0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
46b0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
46c0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
46d0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
46e0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
46f0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4700: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4710: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4720: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4730: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4740: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4750: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4760: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4770: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4780: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4790: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
47a0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
47b0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
47c0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
47d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
47e0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
47f0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4800: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4810: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4820: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4830: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4840: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4850: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4860: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4870: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4880: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4890: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
48a0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
48b0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
48c0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
48d0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
48e0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
48f0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4900: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4910: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4920: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4930: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4940: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4950: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4960: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4970: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4980: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4990: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
49a0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
49b0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
49c0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
49d0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
49e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49f0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4a00: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4a10: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4a20: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4a30: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4a40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4a50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4a60: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4a70: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4a80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4a90: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4aa0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4ab0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4ac0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4ad0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4ae0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4af0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4b00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4b10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4b20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4b30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4b40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4b50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4b60: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4b70: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4b80: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4b90: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4ba0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4bb0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4bc0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4bd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4bf0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4c00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4c10: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4c20: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4c30: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c50: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4c60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4c70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c90: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4ca0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cb0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4cc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4cd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4ce0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cf0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d10: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4d20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d30: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d50: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4d60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d70: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d90: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4da0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4db0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4dd0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4de0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4df0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e10: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e30: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e50: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4e60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e70: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e90: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4ea0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4eb0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ed0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4ee0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ef0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f10: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4f20: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4f30: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f50: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4f60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f70: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f90: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fb0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fd0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4fe0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ff0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5010: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5020: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5030: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5050: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5060: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5070: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5090: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
50a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50b0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
50c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50d0: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
50e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50f0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5150: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
5160: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5170: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5190: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
51b0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
51c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
51d0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
51e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
51f0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5260: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5270: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5280: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5290: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
52a0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
52b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
52c0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
52d0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
52e0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
52f0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5300: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5310: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5320: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5330: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5350: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5360: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5370: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5380: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5390: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
53a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53b0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
53c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5420: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5430: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5470: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5480: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
54b0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
54c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5500: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5530: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5540: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5570: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5580: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5590: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
55c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
55d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5600: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5610: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5630: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5640: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5650: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5670: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5680: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5690: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56b0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
56c0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
56d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56f0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5700: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5710: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5730: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5740: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5750: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5770: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5780: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5790: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
57d0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
57e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5820: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5830: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5840: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5870: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5880: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5890: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58b0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
58c0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
58d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58e0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
58f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5900: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5910: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5920: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5930: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5940: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5950: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5960: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5970: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5980: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5990: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
59a0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
59b0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
59c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
59d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
59e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
59f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5a00: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5a10: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5a20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5a30: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5a40: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5a60: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5a70: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5a80: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5a90: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5ac0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5ad0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5ae0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5af0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5b00: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5b10: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5b20: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5b30: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5b40: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5b50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5b60: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5b70: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5b80: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5b90: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5ba0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5bb0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5bc0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5bd0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5be0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5bf0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5c00: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5c10: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5c20: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5c30: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5c40: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5c50: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5c60: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5c70: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5c80: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5c90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ca0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5cb0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5cd0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5ce0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5cf0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5d00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5d10: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5d20: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d40: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5d50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d60: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5d70: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5d80: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5d90: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5da0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5db0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5dc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5dd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5de0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e00: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5e10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e20: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5e60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e70: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5e90: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5ea0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ec0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5ed0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ee0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5ef0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5f00: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5f10: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5f20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5f30: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5f40: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5f50: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5f60: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5f70: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5f80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5f90: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5fa0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5fb0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5fc0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5fd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5fe0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5ff0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6000: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6020: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6040: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6050: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6060: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6070: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6080: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6090: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
60a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
60b0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
60c0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
60d0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
60e0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
60f0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6100: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6110: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6120: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6130: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6140: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6150: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6170: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6180: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6190: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
61a0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
61b0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
61c0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
61d0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
61e0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
61f0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6200: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6210: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6220: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6230: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6240: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6250: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6260: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6270: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
6280: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6290: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
62a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
62b0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
62c0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
62d0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
62e0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
62f0: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6300: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6310: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6320: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6330: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6340: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6350: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6360: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6370: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
6380: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
6390: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
63a0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
63b0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
63c0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
63d0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
63e0: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
63f0: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6400: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6410: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6420: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6430: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6440: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
6450: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
6460: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
6470: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
6480: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
6490: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
64a0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
64b0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
64c0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
64d0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
64e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
64f0: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6500: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6510: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6520: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6530: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6540: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
6550: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
6560: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
6570: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
6580: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
6590: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
65a0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
65b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
65c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
65d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
65e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
65f0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6600: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6610: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6620: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6630: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6640: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
6650: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
6660: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
6670: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6680: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
6690: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
66a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
66b0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
66c0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
66d0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
66e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
66f0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6700: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6710: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6720: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6730: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6740: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6750: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6760: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6770: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6780: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6790: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
67a0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
67b0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
67c0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
67d0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
67e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
67f0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6800: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6810: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6820: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6840: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6850: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6860: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6870: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6880: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6890: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
68a0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
68b0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
68c0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
68d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
68e0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
68f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6900: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6910: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6920: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6930: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6940: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
6950: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6960: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
6970: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
6980: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
6990: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
69a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
69b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
69c0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
69d0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
69e0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
69f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6a00: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
6a10: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6a20: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
6a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6a40: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
6a50: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
6a60: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
6a70: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
6a80: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
6a90: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
6aa0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
6ab0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6ac0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
6ad0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6ae0: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6af0: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6b00: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6b10: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
6b20: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b30: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
6b40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6b50: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
6b60: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6b70: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
6b80: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
6b90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6ba0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6bb0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6bc0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6bd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6be0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6bf0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6c00: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6c10: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6c20: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6c30: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6c40: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6c50: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6c60: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6c70: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6c80: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6c90: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6ca0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6cb0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6cc0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6cd0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6ce0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6cf0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6d00: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6d10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d20: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6d30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6d40: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6d60: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6d80: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6d90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6da0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6db0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6dc0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6dd0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6de0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6df0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6e00: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6e10: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6e20: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6e30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6e40: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6e50: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6e60: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6e70: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6e80: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6e90: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6ea0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6eb0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6ec0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6ed0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6ee0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6ef0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6f00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6f10: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6f20: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6f30: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6f40: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6f50: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6f60: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6f70: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6f80: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6f90: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6fa0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6fb0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6fc0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6fd0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6fe0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6ff0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7000: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7010: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7020: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7030: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7040: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7050: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7060: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7070: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7080: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7090: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
70a0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
70b0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
70c0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
70d0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
70e0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
70f0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7100: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7110: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7120: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7130: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7140: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7150: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7160: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7170: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7180: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7190: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
71a0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
71b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
71c0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
71d0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
71e0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
71f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7200: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7210: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7220: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7230: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7240: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7250: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7260: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7270: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7280: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7290: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
72a0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
72b0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
72c0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
72d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
72e0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
72f0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7300: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7310: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7320: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7330: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7340: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7350: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
7360: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
7370: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
7380: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
7390: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
73a0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
73b0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
73c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
73d0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
73e0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
73f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7400: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7410: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7420: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7430: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7440: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7450: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
7460: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7470: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7480: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7490: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
74a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74b0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
74c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74d0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
74e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74f0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7500: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7510: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7520: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7530: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7540: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7550: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
7560: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7570: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7580: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
75a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
75b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
75c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
75d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
75e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
75f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7600: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7610: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7620: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7630: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7640: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7650: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7660: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7670: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7680: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
7690: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
76a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
76b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
76c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
76d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
76e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
76f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7700: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7710: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7720: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7730: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7740: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7760: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7770: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7780: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
7790: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
77a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
77b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
77c0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
77d0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
77e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
77f0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7800: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7810: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7820: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7830: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7840: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
7850: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
7860: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7870: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7880: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
7890: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
78a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
78b0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
78c0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
78d0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
78e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
78f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7900: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7910: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7920: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7930: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7940: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7980: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7990: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
79a0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
79b0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
79c0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
79d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
79e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
79f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7a00: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7a10: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7a20: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7a30: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7a40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
7a50: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7a60: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7a70: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7a80: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
7a90: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
7aa0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7ab0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7ac0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7ad0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7ae0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7af0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7b00: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7b10: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7b20: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7b30: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7b40: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7b50: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7b60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7b70: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7b80: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7b90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ba0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
7bb0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
7bc0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
7bd0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
7c00: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
7c10: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
7c20: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
7c30: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
7c40: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
7c50: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7c60: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7c70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7c80: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
7c90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7ca0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7cb0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7cc0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7cd0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7ce0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7cf0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
7d00: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
7d10: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
7d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
7d30: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
7d40: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
7d50: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7d60: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7d70: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7d80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7d90: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7da0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7db0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7dd0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7de0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7df0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
7e10: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
7e20: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
7e30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
7e40: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
7e50: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7e60: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7e70: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7e80: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7e90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7ea0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7eb0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7ec0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ed0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7ee0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7ef0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7f00: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
7f10: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
7f20: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
7f30: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
7f40: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
7f50: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7f60: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7f70: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7f80: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7f90: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7fa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7fb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7fc0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7fd0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7fe0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7ff0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8000: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8010: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8020: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8030: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8040: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8050: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8060: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8070: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8080: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8090: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
80a0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
80b0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
80c0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
80d0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
80e0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
80f0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8100: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8110: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8120: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8130: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8140: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8150: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8160: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
8170: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
8180: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
8190: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
81a0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
81b0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
81c0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
81d0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
81e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
81f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8200: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8210: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8220: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8230: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8240: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8250: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8260: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8270: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8280: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
8290: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
82a0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
82b0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
82c0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
82d0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
82e0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
82f0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8300: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystems..**.** Th
8310: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8320: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8330: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8340: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8350: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8360: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8370: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8380: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
8390: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
83a0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
83b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83c0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
83d0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
83e0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
83f0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ion..**.** ^(The
8400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8410: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8420: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8430: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8440: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8450: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8460: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8470: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8480: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8490: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
84a0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
84b0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
84c0: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
84d0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
84e0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
84f0: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8500: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8510: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8520: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8530: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8540: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8550: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8560: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8570: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8580: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
8590: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
85a0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
85b0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
85c0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
85d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
85e0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
85f0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8600: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8610: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
8620: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8630: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
8640: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23  quire it.  .*/.#
8650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8660: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
8670: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
8680: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
8690: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
86a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
86b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
86c0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
86d0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
86e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
86f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
8710: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
8720: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8730: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23  K_SIZE       6.#
8740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8750: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8760: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
8770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8780: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 38 0a 0a  _OMITTED     8..
8790: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
87a0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
87b0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
87c0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
87d0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
87e0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
87f0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
8800: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
8810: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
8820: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
8830: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
8840: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
8850: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
8860: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
8870: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
8880: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
8890: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
88a0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
88b0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
88c0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
88d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
88e0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
88f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8900: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
8910: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
8920: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
8930: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
8940: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
8950: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
8960: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
8970: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
8980: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
8990: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
89a0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
89b0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
89c0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
89d0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
89e0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
89f0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
8a00: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
8a10: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
8a20: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
8a30: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
8a40: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
8a50: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
8a60: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
8a70: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
8a80: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
8a90: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
8aa0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
8ab0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
8ac0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
8ad0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
8ae0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
8af0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
8b00: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
8b10: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
8b20: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
8b30: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
8b40: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
8b50: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
8b60: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
8b70: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
8b80: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
8b90: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
8ba0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
8bb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
8bc0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
8bd0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8be0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
8bf0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
8c00: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
8c10: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
8c20: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
8c30: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
8c40: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
8c50: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
8c60: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
8c70: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
8c80: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
8c90: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
8ca0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
8cb0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
8cc0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
8cd0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
8ce0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
8cf0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
8d00: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
8d10: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
8d20: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
8d30: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
8d40: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
8d50: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
8d60: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
8d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
8d80: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
8d90: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
8da0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
8db0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
8dc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
8dd0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
8de0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
8df0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
8e00: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
8e10: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
8e20: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
8e30: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
8e40: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
8e50: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
8e60: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
8e70: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
8e80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
8e90: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
8ea0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
8eb0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
8ec0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
8ed0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
8ee0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
8ef0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
8f00: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
8f10: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
8f20: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
8f30: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
8f40: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
8f50: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
8f60: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
8f70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
8f80: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
8f90: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
8fa0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8fb0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
8fc0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
8fd0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
8fe0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
8ff0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
9000: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
9010: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
9020: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
9030: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
9040: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
9050: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
9060: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
9070: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
9080: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
9090: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
90a0: 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  0 alphanumeric a
90b0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
90c0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
90d0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
90e0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
90f0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
9100: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
9110: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
9120: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
9130: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
9140: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
9150: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
9160: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
9170: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
9180: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
9190: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
91a0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
91b0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
91c0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
91d0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
91e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
91f0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
9200: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
9210: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
9220: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
9230: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
9240: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
9250: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
9260: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
9270: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
9280: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
9290: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
92a0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
92b0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
92c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
92d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
92e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
92f0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
9300: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
9310: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
9320: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9330: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
9340: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
9350: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
9360: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
9370: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
9380: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
9390: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
93a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
93b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
93c0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
93d0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
93e0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
93f0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
9400: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
9410: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
9420: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
9430: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
9440: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
9450: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
9460: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
9470: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
9480: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
9490: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
94a0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
94b0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
94c0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
94d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
94e0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
94f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9500: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
9510: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
9520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
9530: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
9540: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
9550: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9560: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
9570: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
9580: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9590: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
95a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
95b0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
95c0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
95d0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
95e0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
95f0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
9600: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
9610: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
9620: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
9630: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
9640: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
9650: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
9660: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
9670: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
9680: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
9690: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
96a0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
96b0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
96c0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
96d0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
96e0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
96f0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
9700: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
9710: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
9720: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
9730: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
9740: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
9750: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
9760: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
9770: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
9780: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
9790: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
97a0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
97b0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
97c0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
97d0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
97e0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
97f0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
9800: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
9810: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
9820: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
9830: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
9840: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
9850: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
9860: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
9870: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
9880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
9890: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
98a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
98b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
98c0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
98d0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
98e0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
98f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
9900: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
9910: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9920: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
9930: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
9940: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
9950: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
9960: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
9970: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
9980: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
9990: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
99a0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
99b0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
99c0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
99d0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
99e0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
99f0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
9a00: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
9a10: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
9a20: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
9a30: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
9a40: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
9a50: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
9a60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
9a70: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
9a80: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
9a90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
9aa0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
9ab0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
9ac0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
9ad0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
9ae0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
9af0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
9b00: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
9b10: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
9b20: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
9b30: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
9b40: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
9b50: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
9b60: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
9b70: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
9b80: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
9b90: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
9ba0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
9bb0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
9bc0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
9bd0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
9be0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
9bf0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
9c00: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
9c10: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
9c20: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
9c30: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
9c40: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
9c50: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
9c60: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
9c70: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
9c80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9c90: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
9ca0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
9cb0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9cc0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
9cd0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
9ce0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
9cf0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
9d00: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
9d10: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
9d20: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
9d30: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
9d40: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
9d50: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
9d60: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
9d70: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
9d80: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
9d90: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
9da0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
9db0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
9dc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
9dd0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
9de0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9df0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
9e00: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
9e10: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
9e20: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
9e30: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
9e40: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
9e50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
9e60: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
9e70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
9e80: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
9e90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9ea0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
9eb0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
9ec0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
9ed0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
9ee0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
9ef0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
9f00: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
9f10: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
9f20: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
9f30: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
9f40: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
9f50: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
9f60: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
9f70: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
9f80: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
9f90: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
9fa0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9fb0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
9fc0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
9fd0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
9fe0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
9ff0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
a000: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
a010: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
a020: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
a030: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
a040: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
a050: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
a060: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
a070: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
a080: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
a090: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
a0a0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
a0b0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
a0c0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
a0d0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
a0e0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
a0f0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
a100: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
a110: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
a120: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
a130: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
a140: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
a150: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
a160: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
a170: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
a180: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
a190: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
a1a0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
a1b0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
a1c0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
a1d0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
a1e0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
a1f0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
a200: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
a210: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
a220: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
a230: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
a240: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
a250: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
a260: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
a270: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
a280: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
a290: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
a2a0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
a2b0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
a2c0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
a2d0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
a2e0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
a2f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
a300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
a310: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
a320: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
a330: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
a340: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
a350: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
a360: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
a370: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
a380: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
a390: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
a3a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
a3b0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
a3c0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
a3d0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
a3e0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
a3f0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
a400: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
a410: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
a420: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
a430: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
a440: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
a450: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
a460: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
a470: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
a480: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
a490: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
a4a0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
a4b0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
a4c0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
a4d0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
a4e0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
a4f0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
a500: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
a510: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
a520: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
a530: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
a540: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
a550: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
a560: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
a570: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
a580: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
a590: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
a5a0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
a5b0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
a5c0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
a5d0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
a5e0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
a5f0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
a600: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
a610: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
a620: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
a630: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
a640: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
a650: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
a660: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
a670: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
a680: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
a690: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
a6a0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
a6b0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
a6c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
a6d0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
a6e0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
a6f0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
a700: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
a710: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
a720: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
a730: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
a740: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
a750: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
a760: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
a770: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
a780: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
a790: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
a7a0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
a7b0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
a7c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
a7d0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
a7e0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
a7f0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
a800: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
a810: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
a820: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
a830: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
a840: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
a850: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
a860: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
a870: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
a880: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
a890: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
a8a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
a8b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
a8c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
a8d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
a8e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
a8f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
a900: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
a910: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
a920: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
a930: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
a940: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
a950: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
a960: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
a970: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
a980: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
a990: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
a9a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
a9b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
a9c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
a9d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
a9e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
a9f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
aa00: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
aa10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
aa20: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
aa30: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
aa40: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
aa50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
aa60: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
aa70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
aa80: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
aa90: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
aaa0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
aab0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
aac0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
aad0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
aae0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
aaf0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
ab00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ab10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ab20: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
ab30: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ab40: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ab50: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ab60: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
ab70: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ab80: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
ab90: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
aba0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
abb0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
abc0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
abd0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
abe0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
abf0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
ac00: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
ac10: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
ac20: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
ac30: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
ac40: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
ac50: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ac60: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
ac70: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
ac80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ac90: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
aca0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
acb0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
acc0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
acd0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ace0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
acf0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
ad00: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
ad10: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
ad20: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
ad30: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
ad40: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
ad50: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
ad60: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
ad70: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ad80: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ad90: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
ada0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
adb0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
adc0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
add0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
ade0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
adf0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
ae00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ae10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ae20: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
ae30: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
ae40: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
ae50: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
ae60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ae70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
ae80: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
ae90: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
aea0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
aeb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
aec0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
aed0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
aee0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
aef0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
af00: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
af10: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
af20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
af30: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
af40: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
af50: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
af60: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
af70: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
af80: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
af90: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
afa0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
afb0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
afc0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
afd0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
afe0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
aff0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
b000: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
b010: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
b020: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
b030: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
b040: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
b050: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
b060: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
b070: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
b080: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
b090: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
b0a0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
b0b0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
b0c0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
b0d0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
b0e0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
b0f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b100: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
b110: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
b120: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
b130: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
b140: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
b150: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
b160: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
b170: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
b180: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
b190: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
b1a0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
b1b0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
b1c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b1d0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
b1e0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
b1f0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
b200: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
b210: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
b220: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
b230: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
b240: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
b250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
b260: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
b270: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
b280: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
b290: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
b2a0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
b2b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
b2c0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
b2d0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
b2e0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
b2f0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
b300: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
b310: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
b320: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
b330: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
b340: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
b350: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b360: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
b370: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
b380: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
b390: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
b3a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b3b0: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
b3c0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
b3d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
b3e0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
b3f0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
b400: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
b410: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
b420: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
b430: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
b440: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
b450: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b460: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
b470: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
b480: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
b490: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
b4a0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
b4b0: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
b4c0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
b4d0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b4e0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
b4f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
b500: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
b510: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
b520: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
b530: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
b540: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
b550: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b560: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
b570: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
b580: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
b590: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
b5a0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
b5b0: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
b5c0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
b5d0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
b5e0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
b5f0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
b600: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
b610: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
b620: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
b630: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
b640: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
b650: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
b660: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
b670: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
b680: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
b690: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
b6a0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
b6b0: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
b6c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
b6d0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
b6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
b6f0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
b700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b710: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
b720: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
b730: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
b740: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
b750: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
b760: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
b770: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
b780: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
b790: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
b7a0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
b7b0: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
b7c0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
b7d0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
b7e0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
b7f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
b800: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
b810: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
b820: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
b830: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
b840: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
b850: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
b860: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
b870: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
b880: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
b890: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
b8a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
b8b0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
b8c0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
b8d0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
b8e0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
b8f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
b900: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
b910: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
b920: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
b930: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
b940: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
b950: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
b960: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
b970: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
b980: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
b990: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
b9a0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
b9b0: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
b9c0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
b9d0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
b9e0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
b9f0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ba00: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ba10: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ba20: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ba30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ba40: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ba50: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ba60: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ba70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ba80: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ba90: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
baa0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
bab0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
bac0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
bad0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
bae0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
baf0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
bb00: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
bb10: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
bb20: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
bb30: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
bb40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bb50: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
bb60: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
bb70: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
bb80: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
bb90: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
bba0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
bbb0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
bbc0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
bbd0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
bbe0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
bbf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bc00: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
bc10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bc20: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
bc30: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
bc40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
bc50: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
bc60: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
bc70: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
bc80: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
bc90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bca0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
bcb0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
bcc0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
bcd0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
bce0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
bcf0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
bd00: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
bd10: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
bd20: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
bd30: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
bd40: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
bd50: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
bd60: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
bd70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bd80: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
bd90: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
bda0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
bdb0: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
bdc0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
bdd0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
bde0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bdf0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
be00: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
be10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
be20: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
be30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
be40: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
be50: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
be60: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
be70: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
be80: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
be90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bea0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
beb0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
bec0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
bed0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
bee0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
bef0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
bf00: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
bf10: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
bf20: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
bf30: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
bf40: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
bf50: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
bf60: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
bf70: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
bf80: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
bf90: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
bfa0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
bfb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
bfc0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
bfd0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
bff0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
c000: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
c010: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
c020: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
c030: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
c040: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
c050: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
c060: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
c070: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
c080: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c090: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
c0a0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
c0b0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
c0c0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
c0d0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
c0e0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
c0f0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
c100: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
c110: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
c120: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
c130: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
c140: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
c150: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
c160: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
c170: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
c180: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
c190: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
c1a0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
c1b0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
c1c0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
c1d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c1e0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
c1f0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
c200: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
c210: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
c220: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
c230: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
c240: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
c250: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
c260: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
c270: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
c280: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
c290: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
c2a0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
c2b0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
c2c0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
c2d0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
c2e0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
c2f0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
c300: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
c310: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
c320: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
c330: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
c340: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
c350: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
c360: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
c370: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
c380: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
c390: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
c3a0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
c3b0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
c3c0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
c3d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
c3e0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
c3f0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
c400: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
c410: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
c420: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
c430: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
c440: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
c450: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
c460: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
c470: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
c480: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
c490: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
c4a0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
c4b0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
c4c0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
c4d0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
c4e0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
c4f0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
c500: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
c510: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
c520: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
c530: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
c540: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c550: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
c560: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
c570: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
c580: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
c590: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
c5a0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
c5b0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
c5c0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
c5d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
c5e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c5f0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
c600: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
c610: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
c620: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
c630: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
c640: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
c650: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
c660: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
c670: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c680: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
c690: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c6a0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
c6b0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
c6c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
c6d0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
c6e0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
c6f0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
c700: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
c710: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
c720: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
c730: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
c740: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
c750: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
c760: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
c770: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
c780: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
c790: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
c7a0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
c7b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
c7c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c7d0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
c7e0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
c7f0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
c800: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
c810: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
c820: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
c830: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
c840: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
c850: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
c860: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
c870: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
c880: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
c890: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
c8a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
c8b0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
c8c0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
c8d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
c8e0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
c8f0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
c900: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
c910: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
c920: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
c930: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
c940: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
c950: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
c960: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
c970: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
c980: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
c990: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
c9a0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
c9b0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
c9c0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
c9d0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
c9e0: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
c9f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ca00: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
ca10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
ca20: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
ca30: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
ca40: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
ca50: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
ca60: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
ca70: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
ca80: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
ca90: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
caa0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
cab0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
cac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
cad0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
cae0: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
caf0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
cb00: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
cb10: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
cb20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
cb30: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
cb40: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
cb50: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
cb60: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
cb70: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
cb80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cb90: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
cba0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
cbb0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
cbc0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
cbd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
cbe0: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
cbf0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
cc00: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cc10: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
cc20: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
cc30: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
cc40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cc50: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
cc60: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
cc70: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
cc80: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
cc90: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
cca0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
ccb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ccc0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
ccd0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
cce0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ccf0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
cd00: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
cd10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
cd20: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
cd30: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
cd40: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
cd50: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
cd60: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cd70: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
cd80: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
cd90: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
cda0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
cdb0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
cdc0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
cdd0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
cde0: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
cdf0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
ce00: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ce10: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
ce20: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
ce30: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
ce40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ce50: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ce60: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
ce70: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
ce80: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
ce90: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
cea0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
ceb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
cec0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
ced0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
cee0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
cef0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
cf00: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
cf10: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
cf20: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
cf30: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
cf40: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
cf50: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
cf60: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
cf70: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
cf80: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
cf90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cfa0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
cfb0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
cfc0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
cfd0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
cfe0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
cff0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
d000: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
d010: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
d020: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
d030: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
d040: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
d050: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
d060: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
d070: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
d080: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
d090: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
d0a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
d0b0: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
d0c0: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
d0d0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
d0e0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
d0f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d100: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
d110: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
d120: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
d130: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
d140: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
d150: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
d160: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
d170: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
d180: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
d190: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
d1a0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
d1b0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
d1c0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
d1d0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
d1e0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
d1f0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
d200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d210: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
d220: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
d230: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d240: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
d250: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
d260: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
d270: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
d280: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
d290: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
d2a0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
d2b0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
d2c0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
d2d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d2e0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
d2f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
d300: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
d310: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
d320: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
d330: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
d340: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d350: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
d360: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d370: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
d380: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
d390: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
d3a0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
d3b0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
d3c0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
d3d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d3e0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
d3f0: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
d400: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
d410: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
d420: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
d430: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
d440: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d450: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
d460: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
d470: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
d480: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
d490: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
d4a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
d4b0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
d4c0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
d4d0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
d4e0: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
d4f0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
d500: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
d510: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
d520: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
d530: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
d540: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
d550: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
d560: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
d570: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
d580: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
d590: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
d5a0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
d5b0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
d5c0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
d5d0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
d5e0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
d5f0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
d600: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d610: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
d620: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
d630: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
d640: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
d650: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
d660: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
d670: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
d680: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
d690: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
d6a0: 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d  lloc and xFree m
d6b0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
d6c0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
d6d0: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
d6e0: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
d6f0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
d700: 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78  ibrary..** The x
d710: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d  Realloc method m
d720: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65  ust work like re
d730: 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65  alloc() from the
d740: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
d750: 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ary.** with the 
d760: 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69  exception that i
d770: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
d780: 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f  ument to xReallo
d790: 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52  c is zero,.** xR
d7a0: 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61  ealloc must be a
d7b0: 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74   no-op - it must
d7c0: 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79   not perform any
d7d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a   allocation or.*
d7e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  * deallocation. 
d7f0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
d800: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
d810: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
d820: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
d830: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
d840: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
d850: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
d860: 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e  up..** And so in
d870: 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f   cases where xRo
d880: 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74  undup always ret
d890: 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20  urns a positive 
d8a0: 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c  number,.** xReal
d8b0: 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20  loc can perform 
d8c0: 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73  exactly as the s
d8d0: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
d8e0: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a  realloc() and.**
d8f0: 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d   still be in com
d900: 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69  pliance with thi
d910: 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e  s specification.
d920: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
d930: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
d940: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
d950: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d960: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
d970: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
d980: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
d990: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
d9a0: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
d9b0: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
d9c0: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
d9d0: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
d9e0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
d9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
da00: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
da10: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
da20: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
da30: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
da40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
da50: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
da60: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
da70: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
da80: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
da90: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
daa0: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
dab0: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
dac0: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
dad0: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
dae0: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
daf0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
db00: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
db10: 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
db20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
db30: 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
db40: 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
db50: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
db60: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
db70: 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
db80: 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
db90: 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
dba0: 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
dbb0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
dbc0: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
dbd0: 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
dbe0: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
dbf0: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
dc00: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
dc10: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
dc20: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
dc30: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
dc40: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
dc50: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
dc60: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
dc70: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
dc80: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
dc90: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
dca0: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
dcb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dcc0: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
dcd0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
dce0: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
dcf0: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
dd00: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
dd10: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
dd20: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
dd30: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
dd40: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
dd50: 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
dd60: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
dd70: 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
dd80: 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
dd90: 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
dda0: 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
ddb0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
ddc0: 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
ddd0: 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
dde0: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
ddf0: 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
de00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
de10: 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
de20: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
de30: 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
de40: 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
de50: 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
de60: 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
de70: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
de80: 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
de90: 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
dea0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
deb0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
dec0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ded0: 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
dee0: 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
def0: 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
df00: 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
df10: 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
df20: 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
df30: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
df40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
df50: 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
df60: 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
df70: 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
df80: 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
df90: 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
dfa0: 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
dfb0: 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
dfc0: 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
dfd0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
dfe0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
dff0: 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
e000: 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
e010: 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
e020: 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
e030: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e040: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
e050: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
e060: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
e070: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
e080: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
e090: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
e0a0: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
e0b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e0c0: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
e0d0: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
e0e0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
e0f0: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
e100: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
e110: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
e120: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
e130: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
e140: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
e150: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
e160: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
e170: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
e180: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
e190: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
e1a0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
e1b0: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
e1c0: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
e1d0: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
e1e0: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
e1f0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
e200: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
e210: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e220: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
e230: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
e240: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
e250: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
e260: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
e270: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
e280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e290: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
e2a0: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
e2b0: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
e2c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e2d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
e2e0: 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
e2f0: 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
e300: 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
e310: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
e320: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
e330: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
e340: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
e350: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
e360: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
e370: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
e380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e390: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
e3a0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
e3b0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
e3c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
e3d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
e3f0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
e400: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
e410: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
e420: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
e430: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
e440: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
e450: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
e460: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
e470: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
e480: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
e490: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
e4a0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
e4b0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
e4c0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
e4d0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
e4e0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
e4f0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
e500: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
e510: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
e520: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
e530: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e540: 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
e550: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
e560: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
e570: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
e580: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
e590: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
e5a0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
e5b0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
e5c0: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
e5d0: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e5e0: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e5f0: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
e600: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
e610: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
e620: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
e630: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
e640: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
e650: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
e660: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
e670: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
e680: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
e690: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
e6a0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
e6b0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
e6c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
e6d0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
e6e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e6f0: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
e700: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
e710: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
e720: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
e730: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
e740: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
e750: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
e760: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
e770: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
e780: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
e790: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
e7a0: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
e7b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e7c0: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
e7d0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e7e0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e7f0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e800: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e810: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e820: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e830: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e840: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e850: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e860: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e870: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e880: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e890: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e8a0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e8b0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e8c0: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e8d0: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e8e0: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e8f0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e900: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e910: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e920: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e930: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e940: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e950: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e960: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e970: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e980: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e990: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e9a0: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e9b0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e9c0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e9d0: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e9e0: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e9f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ea00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ea10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ea20: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
ea30: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
ea40: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
ea50: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
ea60: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
ea70: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
ea80: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
ea90: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
eaa0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
eab0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
eac0: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
ead0: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
eae0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
eaf0: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
eb00: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
eb10: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
eb20: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
eb30: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
eb40: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
eb50: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
eb60: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
eb70: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
eb80: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
eb90: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
eba0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
ebb0: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
ebc0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
ebd0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ebe0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
ebf0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ec00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ec10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ec20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ec30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ec40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ec50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ec60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ec70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ec80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ec90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
eca0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
ecb0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
ecc0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
ecd0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
ece0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
ecf0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
ed00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ed10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
ed20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
ed30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
ed40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
ed50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
ed60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
ed70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
ed80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
ed90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
eda0: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
edb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
edc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
edd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ede0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
edf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ee00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ee10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
ee20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
ee30: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
ee40: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
ee50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
ee60: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
ee70: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ee80: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
ee90: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
eea0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
eeb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
eec0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
eed0: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
eee0: 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
eef0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
ef00: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
ef10: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ef20: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ef30: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ef40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ef50: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ef60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
ef70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
ef80: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
ef90: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
efa0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
efb0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
efc0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
efd0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
efe0: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
eff0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f000: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
f010: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
f020: 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
f030: 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
f040: 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
f050: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
f060: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
f070: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
f080: 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
f090: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
f0a0: 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
f0b0: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
f0c0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
f0d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f0e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
f0f0: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f100: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f110: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f120: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f130: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
f140: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
f150: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
f160: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
f170: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
f180: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
f190: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
f1a0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
f1b0: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
f1c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f1d0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
f1e0: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
f1f0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
f200: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
f210: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
f220: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
f230: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
f240: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
f250: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
f260: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
f270: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
f280: 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
f290: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f2a0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
f2b0: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
f2c0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
f2d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
f2e0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
f2f0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
f300: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
f310: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
f320: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
f330: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
f340: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
f350: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
f360: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
f370: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
f380: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f390: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
f3a0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
f3b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
f3c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
f3d0: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
f3e0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
f3f0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f400: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
f410: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f420: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
f430: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
f440: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
f450: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
f460: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f470: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
f480: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
f490: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f4a0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
f4b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
f4c0: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
f4d0: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
f4e0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
f4f0: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
f500: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
f510: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
f520: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
f530: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
f540: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
f550: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f560: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
f570: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f580: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
f590: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f5a0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f5b0: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f5c0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f5d0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f5e0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
f5f0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
f600: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
f610: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
f620: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
f630: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
f640: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
f650: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
f660: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
f670: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
f680: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
f690: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
f6a0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
f6b0: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
f6c0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
f6d0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
f6e0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
f6f0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
f700: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f710: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
f720: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
f730: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
f740: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
f750: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
f760: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
f770: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
f780: 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
f790: 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
f7a0: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
f7b0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
f7c0: 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
f7d0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
f7e0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
f7f0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f800: 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
f810: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
f820: 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
f830: 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
f840: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
f850: 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
f860: 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
f870: 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
f880: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
f890: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
f8a0: 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
f8b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
f8c0: 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
f8d0: 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
f8e0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
f8f0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
f900: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
f910: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
f920: 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
f930: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f940: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
f950: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
f960: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
f970: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
f980: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
f990: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
f9a0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
f9b0: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
f9c0: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
f9d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
f9e0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
f9f0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
fa00: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
fa10: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
fa20: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
fa30: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
fa40: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
fa50: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
fa60: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
fa70: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
fa80: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
fa90: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
faa0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
fab0: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
fac0: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
fad0: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
fae0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
faf0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
fb00: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
fb10: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
fb20: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
fb30: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
fb40: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
fb50: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
fb60: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
fb70: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
fb80: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
fb90: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
fba0: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
fbb0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
fbc0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
fbd0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
fbe0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
fbf0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
fc00: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
fc10: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
fc20: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
fc30: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
fc40: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
fc50: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
fc60: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
fc70: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
fc80: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
fc90: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
fca0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
fcb0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
fcc0: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
fcd0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
fce0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
fcf0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
fd00: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
fd10: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
fd20: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
fd30: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
fd40: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
fd50: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
fd60: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
fd70: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
fd80: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
fd90: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
fda0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
fdb0: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
fdc0: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
fdd0: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
fde0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
fdf0: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
fe00: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
fe10: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
fe20: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
fe30: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
fe40: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
fe50: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
fe60: 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
fe70: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fe80: 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
fe90: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
fea0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
feb0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
fec0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
fed0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
fee0: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
fef0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ff00: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
ff10: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
ff20: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
ff30: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
ff40: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
ff50: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
ff60: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
ff70: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
ff80: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
ff90: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
ffa0: 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
ffb0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
ffc0: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
ffd0: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
ffe0: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
fff0: 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
10000 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
10010 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
10020 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
10030 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
10040 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
10050 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
10060 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
10070 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
10080 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
10090 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
100a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
100b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
100c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
100d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
100e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
100f0 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
10100 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
10110 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
10120 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
10130 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
10140 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
10150 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
10160 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
10170 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
10180 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
10190 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
101a0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
101b0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
101c0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
101d0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
101e0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
101f0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
10200 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
10210 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
10220 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
10230 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
10240 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
10250 65 64 20 61 74 20 32 5e 31 32 2e 20 52 65 61 73  ed at 2^12. Reas
10260 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
10270 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
10280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
10290 20 61 72 65 20 32 5e 35 20 74 68 72 6f 75 67 68   are 2^5 through
102a0 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a   2^8.</dd>.**.**
102b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
102c0 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
102d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
102e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
102f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10300 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
10310 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10320 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10330 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10340 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10350 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10360 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
10370 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
10380 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
10390 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
103a0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
103b0 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
103c0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
103d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
103e0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
103f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
10400 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
10410 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10420 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10430 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
10440 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
10450 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
10460 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
10470 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10480 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
10490 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
104a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
104b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
104c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
104d0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
104e0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
104f0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
10500 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
10510 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
10520 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10530 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10540 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
10550 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10560 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
10570 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
10580 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10590 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
105a0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
105b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
105c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
105d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
105e0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
105f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10600 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10610 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10620 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10630 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10640 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
10650 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10660 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
10670 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
10680 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
10690 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
106a0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
106b0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
106c0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
106d0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
106e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
106f0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
10700 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
10710 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
10720 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
10730 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
10740 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
10750 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
10760 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10770 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10780 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10790 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
107a0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
107b0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
107c0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
107d0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
107e0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
107f0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
10800 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
10810 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10820 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
10830 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10840 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
10850 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
10860 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10870 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
10880 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10890 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
108a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
108b0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
108c0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
108d0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
108e0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
108f0 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
10900 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
10910 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
10920 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
10930 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
10940 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
10950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10960 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10970 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
10980 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
10990 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
109a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
109b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
109c0 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
109d0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
109e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
109f0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
10a00 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
10a10 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
10a20 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
10a30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10a40 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
10a50 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
10a60 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
10a70 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
10a80 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
10a90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
10aa0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
10ab0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
10ac0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10ad0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
10ae0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10af0 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a  FIG_PCACHE</dt>.
10b00 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10b10 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
10b20 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
10b30 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
10b40 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
10b50 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10b60 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  s] object.  This
10b70 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
10b80 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
10b90 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ** to a custom p
10ba0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
10bb0 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51  entation.)^  ^SQ
10bc0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
10bd0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
10be0 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
10bf0 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
10c00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
10c10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10c30 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  PCACHE]] <dt>SQL
10c40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
10c50 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10c60 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10c70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10c80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10c90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10ca0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
10cb0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
10cc0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
10cd0 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
10ce0 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
10cf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10d00 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
10d10 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
10d20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10d30 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
10d40 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
10d50 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
10d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10d70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
10d80 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
10d90 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
10da0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
10db0 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
10dc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
10dd0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
10de0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
10df0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
10e00 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
10e10 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
10e20 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
10e30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
10e40 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
10e50 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
10e60 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
10e70 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
10e80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
10e90 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
10ea0 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
10eb0 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
10ec0 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
10ed0 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
10ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
10ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
10f00 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
10f10 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
10f20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
10f30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
10f40 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
10f50 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
10f60 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
10f70 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
10f80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
10f90 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
10fa0 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
10fb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
10fc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
10fd0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10fe0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
10ff0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
11000 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
11010 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
11020 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
11030 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
11040 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
11050 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
11060 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
11070 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
11080 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
11090 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
110a0 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
110b0 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
110c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
110d0 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
110e0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
110f0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
11100 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11110 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
11120 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
11130 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
11140 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
11150 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
11160 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
11170 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
11180 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
11190 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
111a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
111b0 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
111c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
111d0 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
111e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
111f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
11200 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
11210 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
11220 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
11230 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
11240 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
11250 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
11260 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
11270 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
11280 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
11290 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
112a0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
112b0 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
112c0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
112d0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
112e0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
112f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
11300 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
11310 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
11320 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
11330 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
11340 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
11350 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
11360 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
11370 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
11380 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
11390 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
113a0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
113b0 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
113c0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
113d0 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
113e0 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
113f0 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
11400 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
11410 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
11420 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
11430 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
11440 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
11450 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
11460 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
11470 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
11480 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
11490 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
114a0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
114b0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
114c0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
114d0 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
114e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
114f0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11500 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
11510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11520 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11530 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
11540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11550 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11560 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
11570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11580 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
11590 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
115a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
115b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
115c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
115d0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
115e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
115f0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
11600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
11610 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
11620 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
11630 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
11640 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
11650 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
11660 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
11670 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
11680 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11690 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
116a0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
116b0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
116c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
116d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
116e0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
116f0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
11700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11710 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
11720 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11730 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11740 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11750 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
11760 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
11770 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
11780 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
11790 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
117a0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
117b0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
117c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
117d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
117e0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
117f0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
11800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11810 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
11820 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11830 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11840 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11850 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
11860 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
11870 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
11880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11890 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
118a0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
118b0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
118c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
118d0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
118e0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a   /* int */../*.*
118f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
11900 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
11910 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
11920 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
11930 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11940 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11950 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11960 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11970 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11980 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
11990 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
119a0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
119b0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
119c0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
119d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
119e0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
119f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
11a00 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11a10 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
11a20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
11a30 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
11a40 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11a50 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11a60 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11a70 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11a80 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
11a90 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11aa0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11ab0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
11ac0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
11ad0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
11ae0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
11af0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11b00 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
11b10 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
11b20 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
11b30 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
11b40 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
11b50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
11b60 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11b70 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
11b80 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11b90 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
11ba0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
11bb0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
11bc0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
11bd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
11be0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
11bf0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
11c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
11c10 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
11c20 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
11c30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
11c40 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11c50 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
11c60 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
11c70 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
11c80 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11c90 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
11ca0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
11cb0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
11cc0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
11cd0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
11ce0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
11cf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
11d00 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
11d10 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
11d20 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
11d30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
11d40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11d50 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
11d60 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
11d70 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
11d80 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
11d90 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
11da0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
11db0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
11dc0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
11dd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
11de0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
11df0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
11e00 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
11e10 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
11e20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
11e30 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
11e40 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
11e50 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
11e60 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
11e70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11e80 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
11e90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11ea0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
11eb0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
11ec0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
11ed0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
11ee0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
11ef0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
11f00 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
11f10 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
11f20 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
11f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11f40 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
11f50 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
11f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
11f70 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
11f80 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
11f90 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
11fa0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
11fb0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
11fc0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
11fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
11fe0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
11ff0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12000 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
12010 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
12020 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
12030 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
12040 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
12050 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
12060 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
12070 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
12080 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
12090 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
120a0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
120b0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
120c0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
120d0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
120e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
120f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
12100 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
12110 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
12120 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
12130 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
12140 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
12150 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
12160 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
12170 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12180 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
12190 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
121a0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
121b0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
121c0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
121d0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
121e0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
121f0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
12200 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
12210 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
12220 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
12230 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
12240 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
12250 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
12260 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
12270 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
12280 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
12290 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
122a0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
122b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
122c0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
122d0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
122e0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
122f0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
12300 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
12310 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
12320 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
12330 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
12340 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
12350 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12360 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
12370 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
12380 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12390 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
123a0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
123b0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
123c0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
123d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
123e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
123f0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
12400 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
12410 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
12420 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
12430 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
12440 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
12450 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
12460 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12470 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12480 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
12490 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
124a0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
124b0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
124c0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
124d0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
124e0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
124f0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
12500 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
12510 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
12520 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
12530 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
12540 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
12550 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
12560 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
12570 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
12580 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
12590 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
125a0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
125b0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
125c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
125d0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
125e0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
125f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
12600 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
12610 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
12620 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
12630 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
12640 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
12650 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
12660 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
12670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
12680 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
12690 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
126a0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
126b0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
126c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
126d0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
126e0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
126f0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
12700 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
12710 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
12720 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
12730 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
12740 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
12750 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
12760 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
12770 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
12780 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12790 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
127a0 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
127b0 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
127c0 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
127d0 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
127e0 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
127f0 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
12800 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
12810 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
12820 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
12830 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
12840 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
12850 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
12860 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
12870 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
12880 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
12890 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
128a0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
128b0 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
128c0 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
128d0 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
128e0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
128f0 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
12900 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
12910 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
12920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
12930 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
12940 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
12950 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
12960 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
12970 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
12980 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
12990 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
129a0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
129b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
129c0 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65  ^As of SQLite ve
129d0 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69  rsion 3.7.7, thi
129e0 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  s routines.** re
129f0 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69  cords the last i
12a00 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62  nsert rowid of b
12a10 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62  oth ordinary tab
12a20 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c  les and [virtual
12a30 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66   tables]..** ^If
12a40 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
12a50 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
12a60 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
12a70 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
12a80 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
12a90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
12aa0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
12ab0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
12ac0 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
12ad0 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
12ae0 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
12af0 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
12b00 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
12b10 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
12b20 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
12b30 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
12b40 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
12b50 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
12b60 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
12b70 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
12b80 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
12b90 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
12ba0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
12bb0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
12bc0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
12bd0 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
12be0 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
12bf0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
12c00 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
12c10 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
12c20 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
12c30 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
12c40 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12c50 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
12c60 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
12c70 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
12c80 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
12c90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12ca0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
12cb0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
12cc0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
12cd0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
12ce0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
12cf0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
12d00 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
12d10 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
12d20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
12d30 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
12d40 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
12d50 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
12d60 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
12d70 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
12d80 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
12d90 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
12da0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
12db0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
12dc0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
12dd0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
12de0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
12df0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
12e00 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
12e10 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
12e20 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
12e30 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
12e40 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
12e50 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
12e60 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
12e70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
12e80 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
12e90 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
12ea0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
12eb0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
12ec0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
12ed0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
12ee0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
12ef0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
12f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
12f10 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
12f20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
12f30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
12f40 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
12f50 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
12f60 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
12f70 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
12f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12f90 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
12fa0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
12fb0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
12fc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
12fd0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
12fe0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
12ff0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
13000 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
13010 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
13020 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
13030 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
13040 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
13050 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
13060 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
13070 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
13080 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
13090 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  d]..*/.SQLITE_AP
130a0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
130b0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
130c0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
130d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
130e0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
130f0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
13100 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
13110 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
13120 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
13130 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
13140 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
13150 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
13160 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
13170 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
13180 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
13190 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
131a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
131b0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
131c0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
131d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
131e0 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
131f0 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
13200 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
13210 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
13220 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
13230 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
13240 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
13250 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
13260 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
13270 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
13280 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
13290 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
132a0 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
132b0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
132c0 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
132d0 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
132e0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
132f0 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
13300 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
13310 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
13320 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
13330 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
13340 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
13350 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
13360 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
13370 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
13380 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
13390 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
133a0 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
133b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
133c0 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
133d0 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
133e0 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
133f0 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
13400 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
13410 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
13420 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
13430 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
13440 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
13450 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
13460 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
13470 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
13480 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
13490 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
134a0 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
134b0 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
134c0 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
134d0 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
134e0 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
134f0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
13500 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
13510 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
13520 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
13530 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
13540 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
13550 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
13560 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
13570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
13580 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
13590 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
135a0 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
135b0 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
135c0 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
135d0 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
135e0 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
135f0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
13600 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
13610 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
13620 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
13630 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
13640 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
13650 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
13660 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
13670 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
13680 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
13690 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
136a0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
136b0 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
136c0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
136d0 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
136e0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
136f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
13700 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
13710 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
13720 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
13730 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
13740 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
13750 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
13760 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
13770 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
13780 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
13790 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
137a0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
137b0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
137c0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
137d0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
137e0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
137f0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
13800 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
13810 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
13820 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
13830 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
13840 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
13850 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
13860 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
13870 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
13880 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
13890 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
138a0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
138b0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
138c0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
138d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
138e0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
138f0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
13900 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
13910 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
13920 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
13930 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
13940 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
13950 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
13960 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
13970 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
13980 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
13990 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
139a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
139b0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
139c0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
139d0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
139e0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
139f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
13a00 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13a10 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13a20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
13a30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
13a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
13a50 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
13a60 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
13a70 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
13a80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
13a90 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
13aa0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
13ab0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
13ac0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
13ad0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
13ae0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13af0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
13b00 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
13b10 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
13b20 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
13b30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
13b40 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
13b50 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
13b60 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
13b70 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
13b80 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
13b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13ba0 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
13bb0 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
13bc0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
13bd0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
13be0 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
13bf0 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
13c00 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
13c10 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
13c20 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
13c30 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
13c40 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
13c50 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
13c60 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
13c70 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
13c80 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
13c90 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
13ca0 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
13cb0 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
13cc0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
13cd0 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
13ce0 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
13cf0 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
13d00 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
13d10 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
13d20 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
13d30 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
13d40 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
13d50 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
13d60 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
13d70 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
13d80 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
13d90 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
13da0 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
13db0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
13dc0 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
13dd0 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
13de0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
13df0 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
13e00 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
13e10 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
13e20 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
13e30 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13e40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
13e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
13e60 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
13e70 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
13e80 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
13e90 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
13ea0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
13eb0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
13ec0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
13ed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
13ee0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
13ef0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
13f00 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
13f10 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
13f20 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
13f30 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
13f40 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
13f50 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
13f60 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
13f70 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
13f80 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
13f90 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
13fa0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
13fb0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
13fc0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
13fd0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
13fe0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
13ff0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
14000 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
14010 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
14020 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
14030 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
14040 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
14050 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
14060 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
14070 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
14080 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
14090 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
140a0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
140b0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
140c0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
140d0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
140e0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
140f0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
14100 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
14110 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
14120 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
14130 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
14140 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
14150 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
14160 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
14170 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
14180 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
14190 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
141a0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
141b0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
141c0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
141d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
141e0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
141f0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
14200 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
14210 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
14220 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
14230 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
14240 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
14250 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
14260 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
14270 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
14280 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
14290 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
142a0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
142b0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
142c0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
142d0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
142e0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
142f0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
14300 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
14310 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
14320 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
14330 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
14340 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
14350 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
14360 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14370 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
14380 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
14390 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
143a0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
143b0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
143c0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
143d0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
143e0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
143f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14400 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
14410 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
14420 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
14430 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
14440 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
14450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14460 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
14470 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
14480 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
14490 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
144a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
144b0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
144c0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
144d0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
144e0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
144f0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
14500 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
14510 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
14520 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
14530 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
14540 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
14550 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
14560 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
14570 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
14580 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
14590 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
145a0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
145b0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
145c0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
145d0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
145e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
145f0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
14600 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
14610 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
14620 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
14630 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
14640 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
14650 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
14660 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
14670 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
14680 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
14690 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
146a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
146b0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
146c0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
146d0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
146e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
146f0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
14700 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
14710 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
14720 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14730 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
14740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
14750 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
14760 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
14770 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
14780 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
14790 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
147a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
147b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
147c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
147d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
147e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
147f0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
14800 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
14810 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
14820 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
14830 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
14840 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
14850 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
14860 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
14870 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
14880 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
14890 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
148a0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
148b0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
148c0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
148d0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
148e0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
148f0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
14900 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
14910 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
14920 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
14930 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
14940 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
14950 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
14960 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
14970 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
14980 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
14990 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
149a0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
149b0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
149c0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
149d0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
149e0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
149f0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
14a00 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
14a10 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
14a20 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
14a30 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
14a40 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
14a50 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
14a60 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
14a70 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
14a80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
14a90 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
14aa0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
14ab0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
14ac0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14ad0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
14ae0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
14af0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
14b00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
14b10 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
14b20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
14b30 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
14b40 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
14b50 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
14b60 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
14b70 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
14b80 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
14b90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
14ba0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
14bb0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
14bc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
14bd0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
14be0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
14bf0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
14c00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
14c10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
14c20 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
14c30 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
14c40 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
14c50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
14c60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
14c70 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
14c80 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
14c90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
14ca0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
14cb0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
14cc0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
14cd0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
14ce0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
14cf0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
14d00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
14d10 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
14d20 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14d30 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
14d40 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
14d50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14d60 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
14d70 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
14d80 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  rder..*/.SQLITE_
14d90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
14da0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
14db0 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54  har *sql);.SQLIT
14dc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
14dd0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
14de0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
14df0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14e00 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
14e10 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
14e20 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
14e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
14e40 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
14e50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
14e60 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
14e70 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
14e80 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
14e90 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
14ea0 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
14eb0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
14ec0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
14ed0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
14ee0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
14ef0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
14f00 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
14f10 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
14f20 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
14f30 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
14f40 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
14f50 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
14f60 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
14f70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
14f80 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
14f90 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
14fa0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
14fb0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
14fc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
14fd0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
14fe0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
14ff0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15000 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
15010 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
15020 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
15030 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
15040 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
15050 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15060 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
15070 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
15080 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
15090 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
150a0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
150b0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
150c0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
150d0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
150e0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
150f0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
15100 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
15110 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
15120 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
15130 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
15140 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
15150 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
15160 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
15170 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
15180 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15190 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
151a0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
151b0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
151c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
151d0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
151e0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
151f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
15200 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
15210 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
15220 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
15230 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
15240 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
15250 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
15260 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
15270 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
15280 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
15290 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
152a0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
152b0 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
152c0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
152d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
152e0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
152f0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
15300 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
15310 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
15320 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
15330 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
15340 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
15350 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
15360 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
15370 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
15380 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
15390 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
153a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
153b0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
153c0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
153d0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
153e0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
153f0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
15400 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
15410 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
15420 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
15430 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
15440 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15450 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
15460 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
15470 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
15480 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
15490 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
154a0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
154b0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
154c0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
154d0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
154e0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
154f0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
15500 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
15510 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
15520 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
15530 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
15540 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
15550 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
15560 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
15570 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
15580 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
15590 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
155a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
155b0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
155c0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
155d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
155e0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
155f0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
15600 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15610 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
15620 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
15630 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
15640 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
15650 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
15660 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
15670 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
15680 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
15690 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
156a0 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
156b0 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
156c0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
156d0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
156e0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
156f0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
15700 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
15710 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
15720 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
15730 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
15740 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
15750 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
15760 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
15770 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
15780 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
15790 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
157a0 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
157b0 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
157c0 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
157d0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
157e0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
157f0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
15800 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
15810 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
15820 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
15830 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15840 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
15850 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
15860 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
15870 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
15880 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
15890 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
158a0 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
158b0 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
158c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
158d0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
158e0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
158f0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
15900 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
15910 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
15920 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
15930 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
15940 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
15950 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
15960 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
15970 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15980 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
15990 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
159a0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
159b0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
159c0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
159d0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
159e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
159f0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
15a00 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
15a10 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
15a20 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
15a30 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
15a40 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
15a50 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
15a60 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
15a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15a80 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
15a90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15aa0 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
15ab0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
15ac0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
15ad0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
15ae0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
15af0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
15b00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15b10 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
15b20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
15b30 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
15b40 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
15b50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
15b60 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
15b70 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
15b80 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
15b90 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
15ba0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
15bb0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
15bc0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
15bd0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
15be0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
15bf0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
15c00 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
15c10 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
15c20 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
15c30 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
15c40 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
15c50 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
15c60 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
15c70 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
15c80 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
15c90 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
15ca0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
15cb0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
15cc0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
15cd0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
15ce0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
15cf0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
15d00 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
15d10 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
15d20 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
15d30 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
15d40 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
15d50 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
15d60 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
15d70 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
15d80 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
15d90 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
15da0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
15db0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
15dc0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
15dd0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
15de0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
15df0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
15e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15e10 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
15e20 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
15e30 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
15e40 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
15e50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
15e60 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
15e70 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
15e80 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
15e90 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
15ea0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
15eb0 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ared.)^.*/.SQLIT
15ec0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
15ed0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
15ee0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
15ef0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15f00 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
15f10 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
15f20 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
15f30 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
15f40 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
15f50 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
15f60 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
15f70 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
15f80 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
15f90 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
15fa0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
15fb0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
15fc0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
15fd0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
15fe0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
15ff0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
16000 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16010 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
16020 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
16030 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
16040 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
16050 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
16060 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
16070 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
16080 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
16090 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
160a0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
160b0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
160c0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
160d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
160e0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
160f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
16100 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
16110 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
16120 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
16130 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
16140 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
16150 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
16160 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
16170 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
16180 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
16190 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
161a0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
161b0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
161c0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
161d0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
161e0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
161f0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
16200 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
16210 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
16220 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
16230 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
16240 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
16250 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
16260 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
16270 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
16280 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
16290 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
162a0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
162b0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
162c0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
162d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
162e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
162f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16300 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
16310 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
16320 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
16330 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
16340 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
16350 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
16360 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
16370 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
16380 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
16390 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
163a0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
163b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
163c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
163d0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
163e0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
163f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
16400 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
16410 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
16420 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
16430 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
16440 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16450 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
16460 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
16470 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
16480 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
16490 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
164a0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
164b0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
164c0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
164d0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
164e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
164f0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
16500 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
16510 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
16520 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
16530 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
16540 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
16550 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
16560 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
16570 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
16580 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
16590 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
165a0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
165b0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
165c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
165d0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
165e0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
165f0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
16600 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
16610 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
16620 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16630 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
16640 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16650 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
16660 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16670 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
16680 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
16690 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
166a0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
166b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
166c0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
166d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
166e0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
166f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16700 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
16710 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16720 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
16730 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
16740 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
16750 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
16760 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
16770 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16780 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
16790 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
167a0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
167b0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
167c0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
167d0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
167e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
167f0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
16800 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
16810 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
16820 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
16830 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16840 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
16850 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
16860 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
16870 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
16880 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
16890 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
168a0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
168b0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
168c0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
168d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
168e0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
168f0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
16900 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
16910 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
16920 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
16930 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
16940 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
16950 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
16960 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
16970 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
16980 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
16990 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
169a0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
169b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
169c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
169d0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
169e0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
169f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
16a00 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
16a10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
16a20 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
16a30 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
16a40 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
16a50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
16a60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
16a70 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
16a80 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
16a90 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
16aa0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
16ab0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
16ac0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
16ad0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
16ae0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
16af0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
16b00 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
16b10 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
16b20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
16b30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
16b40 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
16b50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16b60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
16b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
16b80 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
16b90 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
16ba0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
16bb0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
16bc0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
16bd0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
16be0 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
16bf0 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
16c00 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
16c10 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
16c20 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
16c30 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
16c40 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
16c50 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
16c60 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
16c70 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
16c80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
16c90 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
16ca0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
16cb0 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
16cc0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
16cd0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
16ce0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
16cf0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
16d00 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
16d10 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
16d20 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
16d30 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
16d40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
16d50 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
16d60 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
16d70 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
16d80 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
16d90 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
16da0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
16db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
16dc0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
16dd0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
16de0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
16df0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
16e00 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
16e10 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
16e20 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
16e30 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
16e40 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
16e50 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
16e60 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
16e70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
16e80 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
16e90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
16ea0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
16eb0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16ec0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
16ed0 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
16ee0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
16ef0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
16f00 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
16f10 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
16f20 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
16f30 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
16f40 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
16f50 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
16f60 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
16f70 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
16f80 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
16f90 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
16fa0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16fb0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
16fc0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
16fd0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16fe0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
16ff0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
17000 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
17010 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
17020 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
17030 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
17040 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
17050 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
17060 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
17070 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
17080 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
17090 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
170a0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
170b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
170c0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
170d0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
170e0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
170f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
17100 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
17110 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
17120 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
17130 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
17140 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
17150 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
17160 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
17170 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
17180 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
17190 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
171a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
171b0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
171c0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
171d0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
171e0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
171f0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
17200 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
17210 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
17220 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
17230 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
17240 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
17250 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
17260 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
17270 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
17280 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
17290 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
172a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
172b0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
172c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
172d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
172e0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
172f0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
17300 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
17310 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
17320 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
17330 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17340 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
17350 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
17360 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
17370 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
17380 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
17390 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
173a0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
173b0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
173c0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
173d0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
173e0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
173f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
17400 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
17410 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
17420 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
17430 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
17440 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
17450 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
17460 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
17470 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
17480 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
17490 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
174a0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
174b0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
174c0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
174d0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
174e0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
174f0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
17500 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
17510 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
17520 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
17530 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
17540 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
17550 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
17560 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
17570 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
17580 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
17590 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
175a0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
175b0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
175c0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
175d0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
175e0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
175f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
17600 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17610 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
17620 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
17630 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
17640 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
17650 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
17660 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
17670 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
17680 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
17690 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
176a0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
176b0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
176c0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
176d0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
176e0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
176f0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
17700 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
17710 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
17720 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
17730 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
17740 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
17750 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
17760 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
17770 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
17780 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
17790 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
177a0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
177b0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
177c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
177d0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
177e0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
177f0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
17800 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
17810 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17820 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
17830 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
17840 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
17850 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
17860 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
17870 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
17880 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
17890 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
178a0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
178b0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
178c0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
178d0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
178e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
178f0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
17900 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
17910 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
17920 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
17930 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
17940 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
17950 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
17960 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
17970 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
17980 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
17990 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
179a0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
179b0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
179c0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
179d0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
179e0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
179f0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
17a00 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
17a10 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
17a20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
17a30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
17a40 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
17a50 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
17a60 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
17a70 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
17a80 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
17a90 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
17aa0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17ab0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17ac0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
17ad0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
17ae0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
17af0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
17b00 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
17b10 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
17b20 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
17b30 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
17b40 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
17b50 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
17b60 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
17b70 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
17b80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
17b90 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
17ba0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
17bb0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
17bc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
17bd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
17be0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
17bf0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
17c00 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
17c10 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
17c20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
17c30 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
17c40 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
17c50 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
17c60 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
17c70 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
17c80 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
17c90 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  g.)^.*/.SQLITE_A
17ca0 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
17cb0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
17cc0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
17cd0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
17ce0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
17cf0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
17d00 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
17d10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
17d20 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17d30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
17d40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
17d50 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
17d60 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17d70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
17d80 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
17d90 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
17da0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
17db0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
17dc0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
17dd0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
17de0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
17df0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
17e00 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
17e10 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
17e20 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
17e30 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
17e40 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
17e50 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
17e60 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
17e70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
17e80 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
17e90 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
17ea0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
17eb0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
17ec0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
17ed0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
17ee0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
17ef0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
17f00 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
17f10 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
17f20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
17f30 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
17f40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
17f50 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
17f60 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
17f70 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
17f80 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
17f90 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
17fa0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
17fb0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
17fc0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
17fd0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
17fe0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
17ff0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
18000 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
18010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
18020 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
18030 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
18040 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
18050 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
18060 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
18070 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
18080 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
18090 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
180a0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
180b0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
180c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
180d0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
180e0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
180f0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
18100 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
18110 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
18120 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
18130 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
18140 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
18150 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
18160 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
18170 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
18180 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
18190 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
181a0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
181b0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
181c0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
181d0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
181e0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
181f0 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
18200 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
18210 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
18220 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
18230 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
18240 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
18250 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
18260 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
18270 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
18280 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
18290 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
182a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
182b0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
182c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
182d0 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
182e0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
182f0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
18300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18310 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
18320 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
18330 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
18340 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
18350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18360 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
18370 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
18380 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
18390 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
183a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
183b0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
183c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
183d0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
183e0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
183f0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
18400 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
18410 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
18420 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18430 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
18440 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
18450 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18460 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
18470 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
18480 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
18490 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
184a0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
184b0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
184c0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
184d0 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
184e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
184f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18500 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
18510 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
18520 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
18530 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
18540 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
18550 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
18560 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
18570 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
18580 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
18590 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
185a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
185b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
185c0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
185d0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
185e0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
185f0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
18600 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
18610 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
18620 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
18630 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
18640 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
18650 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
18660 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
18670 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
18680 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
18690 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
186a0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
186b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
186c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
186d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
186e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
186f0 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
18700 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
18710 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
18720 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
18730 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
18740 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
18750 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
18760 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
18770 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
18780 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
18790 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
187a0 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
187b0 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
187c0 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
187d0 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
187e0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
187f0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
18800 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
18810 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
18820 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
18830 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
18840 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
18850 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
18860 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
18870 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
18880 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
18890 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
188a0 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
188b0 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
188c0 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
188d0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
188e0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
188f0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
18900 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
18910 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
18920 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
18930 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
18940 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
18950 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
18960 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
18970 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
18980 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
18990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
189a0 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
189b0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
189c0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
189d0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
189e0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
189f0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
18a00 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
18a10 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
18a20 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
18a30 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
18a40 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
18a50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
18a60 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
18a70 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
18a80 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
18a90 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
18aa0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
18ab0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18ac0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
18ad0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
18ae0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
18af0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
18b00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
18b10 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
18b20 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
18b30 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
18b40 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
18b50 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
18b60 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
18b70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18b80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
18b90 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
18ba0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
18bb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
18bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
18bd0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
18be0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
18bf0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
18c00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
18c10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18c20 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
18c30 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
18c40 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
18c50 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
18c60 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
18c70 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
18c80 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
18c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
18ca0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
18cb0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
18cc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
18cd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
18ce0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
18cf0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
18d00 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
18d10 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
18d20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
18d30 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
18d40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
18d50 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
18d60 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
18d70 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
18d80 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
18d90 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
18da0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
18db0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
18dc0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
18dd0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
18de0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
18df0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
18e00 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
18e10 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
18e20 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
18e30 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
18e40 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
18e50 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
18e60 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
18e70 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
18e80 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
18e90 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
18ea0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
18eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
18ec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18ed0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
18ee0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
18ef0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
18f00 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
18f10 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
18f20 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
18f30 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
18f40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
18f50 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
18f60 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
18f70 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
18f80 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
18f90 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
18fa0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
18fb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
18fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
18fd0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
18fe0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
18ff0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
19000 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
19010 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
19020 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
19030 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
19040 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
19050 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
19060 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19070 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
19080 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
19090 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
190a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
190b0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
190c0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
190d0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
190e0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
190f0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
19100 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
19110 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
19120 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
19130 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
19140 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
19150 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
19160 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
19170 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
19180 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
19190 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
191a0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
191b0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
191c0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
191d0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
191e0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
191f0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
19200 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
19210 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
19220 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
19230 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
19240 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
19250 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
19260 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
19270 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
19280 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
19290 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
192a0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
192b0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
192c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
192d0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
192e0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
192f0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
19300 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
19310 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
19320 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
19330 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
19340 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
19350 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
19360 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
19370 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
19380 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
19390 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
193a0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
193b0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
193c0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
193d0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
193e0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
193f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
19400 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
19410 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
19420 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
19430 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
19440 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
19450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19460 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
19470 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
19480 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
19490 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
194a0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
194b0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
194c0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
194d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
194e0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
194f0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
19500 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
19510 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19520 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
19530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19540 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
19550 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
19560 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
19570 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
19580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19590 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
195a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
195b0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
195c0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
195d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
195e0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
195f0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
19600 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
19610 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
19620 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
19630 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
19640 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19650 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
19660 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
19670 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
19680 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
19690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
196a0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
196b0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
196c0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
196d0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
196e0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
196f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
19700 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
19710 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19720 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
19730 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
19740 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
19750 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
19760 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
19770 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
19780 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
19790 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
197a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
197b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
197c0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
197d0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
197e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
197f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
19800 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
19810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19820 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
19830 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
19840 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
19850 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
19860 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
19870 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
19880 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19890 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
198a0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
198b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
198c0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
198d0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
198e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
198f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
19900 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
19910 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
19920 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
19930 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
19940 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
19950 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
19960 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
19970 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
19980 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
19990 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
199a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
199b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
199c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
199d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
199e0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
199f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
19a00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
19a10 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
19a20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19a30 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
19a40 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
19a50 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
19a60 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
19a70 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
19a80 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
19a90 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
19aa0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
19ab0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
19ac0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
19ad0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
19ae0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
19af0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
19b00 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
19b10 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
19b20 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
19b30 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
19b40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
19b50 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
19b60 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
19b70 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
19b80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19b90 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
19ba0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
19bb0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
19bc0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
19bd0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
19be0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
19bf0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
19c00 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
19c10 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
19c20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
19c30 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
19c40 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
19c50 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
19c60 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
19c70 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
19c80 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
19c90 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
19ca0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
19cb0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
19cc0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
19cd0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
19ce0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
19cf0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
19d00 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
19d10 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
19d20 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
19d30 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
19d40 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
19d50 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
19d60 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
19d70 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
19d80 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
19d90 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
19da0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
19db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
19dc0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
19dd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
19de0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
19df0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
19e00 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
19e10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
19e20 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
19e30 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
19e40 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
19e50 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
19e60 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
19e70 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
19e80 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
19e90 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
19ea0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
19eb0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
19ec0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
19ed0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
19ee0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
19ef0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
19f00 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
19f10 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
19f20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19f30 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
19f40 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
19f50 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
19f60 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
19f70 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
19f80 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
19f90 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
19fa0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
19fb0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
19fc0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
19fd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
19fe0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
19ff0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1a000 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1a010 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1a020 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1a030 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1a040 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1a050 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1a060 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1a070 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1a080 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1a090 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1a0a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1a0b0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1a0c0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1a0d0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1a0e0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1a0f0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1a100 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1a110 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1a120 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1a130 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1a140 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1a150 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1a160 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1a170 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1a180 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1a190 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1a1a0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1a1b0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1a1c0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1a1d0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1a1e0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1a1f0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1a200 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1a210 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1a220 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1a230 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1a240 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1a250 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1a260 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1a270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1a280 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1a290 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a2a0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1a2b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a2c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1a2d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1a2e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1a2f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a300 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1a310 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1a320 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1a330 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1a340 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1a350 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1a360 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1a370 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1a380 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1a390 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1a3a0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1a3b0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1a3c0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1a3d0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1a3e0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1a3f0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1a400 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1a410 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a420 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1a430 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1a440 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1a450 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1a460 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a470 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a480 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1a490 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a4a0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1a4b0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1a4c0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1a4d0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1a4e0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1a4f0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1a500 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1a510 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1a520 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1a530 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1a540 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1a550 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1a560 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1a570 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1a580 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1a590 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49   change..*/.SQLI
1a5a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1a5b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a5c0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1a5d0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1a5e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1a5f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a600 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a610 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1a620 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1a630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a640 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1a650 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1a660 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1a670 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1a680 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a690 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1a6a0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1a6b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1a6c0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1a6d0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1a6e0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1a6f0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1a700 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1a710 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1a720 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1a730 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a740 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1a750 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1a760 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1a770 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1a780 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1a790 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1a7a0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
1a7b0 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
1a7c0 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
1a7d0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1a7e0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1a7f0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1a800 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1a810 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1a820 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1a830 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1a840 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1a850 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1a860 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1a870 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1a880 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1a890 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1a8a0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1a8b0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1a8c0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1a8d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a8e0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1a8f0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1a900 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a910 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1a920 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1a930 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1a940 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1a950 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1a960 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a970 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1a980 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1a990 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1a9a0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1a9b0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1a9c0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1a9d0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1a9e0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1a9f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1aa00 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1aa10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1aa20 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1aa30 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1aa40 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1aa50 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1aa60 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1aa70 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1aa80 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1aa90 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1aaa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1aab0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1aac0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1aad0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1aae0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1aaf0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1ab00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1ab10 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1ab20 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1ab30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ab40 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1ab50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1ab60 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1ab70 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1ab80 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1ab90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1aba0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1abb0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1abc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1abd0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1abe0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1abf0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1ac00 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1ac10 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1ac20 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1ac30 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1ac40 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1ac50 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1ac60 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1ac70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ac80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1ac90 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1aca0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1acb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1acc0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1acd0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1ace0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1acf0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ad00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ad10 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1ad20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1ad30 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1ad40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ad50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ad60 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1ad70 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1ad80 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1ad90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ada0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1adb0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1adc0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1add0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ade0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1adf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ae00 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1ae10 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1ae20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ae30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ae40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ae50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1ae60 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1ae70 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ae80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ae90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1aea0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1aeb0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1aec0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1aed0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aee0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1aef0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1af00 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1af10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1af20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1af30 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1af40 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1af50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1af60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1af70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1af80 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1af90 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1afa0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1afb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1afc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1afd0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1afe0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1aff0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b000 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b020 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1b030 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1b040 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b050 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b070 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1b080 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1b090 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b0a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b0c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1b0d0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1b0e0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b0f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b110 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1b120 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1b130 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b140 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b160 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1b170 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1b180 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b190 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b1b0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1b1c0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1b1d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b1e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b1f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1b200 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1b210 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1b220 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b230 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1b250 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1b260 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1b270 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1b280 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1b290 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1b2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b2b0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1b2c0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1b2d0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1b2e0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1b2f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b300 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1b310 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1b320 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b330 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1b340 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1b350 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1b360 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b370 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b380 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1b390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1b3a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b3b0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b3c0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b3d0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1b3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1b3f0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1b400 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b410 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b420 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1b430 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1b440 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1b450 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1b460 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b470 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1b480 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1b490 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1b4a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b4b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b4c0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1b4d0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1b4e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b4f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b510 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1b520 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1b530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b560 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1b570 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1b580 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b590 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1b5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b5b0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1b5c0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1b5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1b5e0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1b5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b600 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1b610 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1b620 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1b630 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1b640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b650 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1b660 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1b670 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1b680 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1b690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b6a0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1b6b0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1b6c0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1b6d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b6e0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1b6f0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1b700 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b710 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1b720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1b730 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1b740 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1b750 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1b760 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1b770 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b780 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1b790 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1b7a0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1b7b0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1b7c0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1b7d0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1b7e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1b7f0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1b800 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1b810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b820 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1b830 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1b840 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1b850 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1b860 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1b870 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1b880 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1b890 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1b8a0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1b8b0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1b8c0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1b8d0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1b8e0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1b8f0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1b900 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1b910 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1b920 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1b930 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1b940 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1b950 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
1b960 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b970 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1b980 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1b990 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1b9a0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1b9b0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1b9c0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1b9d0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1b9e0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1b9f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1ba00 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1ba10 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1ba20 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1ba30 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1ba40 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1ba50 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1ba60 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1ba70 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1ba80 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1ba90 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1baa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1bab0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1bac0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1bad0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1bae0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1baf0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1bb00 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1bb10 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1bb20 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1bb30 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1bb40 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1bb50 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1bb60 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1bb70 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1bb80 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1bb90 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1bba0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1bbb0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1bbc0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1bbd0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1bbe0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1bbf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1bc00 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1bc10 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1bc20 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1bc30 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1bc40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
1bc50 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1bc60 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1bc70 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1bc80 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1bc90 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1bca0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1bcb0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1bcc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bcd0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1bce0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1bcf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1bd00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1bd10 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1bd20 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1bd30 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1bd40 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1bd50 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1bd60 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1bd70 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1bd80 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1bd90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bda0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1bdb0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1bdc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bdd0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1bde0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1bdf0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1be00 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1be10 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1be20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1be30 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1be40 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1be50 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1be60 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1be70 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1be80 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1be90 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1bea0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1beb0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1bec0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1bed0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1bee0 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1bef0 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1bf00 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1bf10 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1bf20 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1bf30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1bf40 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1bf50 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1bf60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1bf70 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1bf80 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1bf90 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1bfa0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1bfb0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1bfc0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1bfd0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1bfe0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1bff0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1c000 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1c010 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1c020 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1c030 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1c040 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1c050 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1c060 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1c070 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1c080 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1c090 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1c0a0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1c0b0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1c0c0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1c0d0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1c0e0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1c0f0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1c100 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1c110 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1c120 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1c130 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1c140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c150 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c160 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1c170 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1c180 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1c190 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1c1a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1c1b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1c1c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c1d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1c1e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1c1f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1c200 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
1c210 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1c220 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c230 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c240 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1c250 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1c260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1c270 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1c280 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1c290 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1c2a0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1c2b0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1c2c0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1c2d0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1c2e0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1c2f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1c300 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1c310 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1c320 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1c330 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1c340 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1c350 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1c360 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1c370 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1c380 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1c390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c3a0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1c3b0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1c3c0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1c3d0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1c3e0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1c3f0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1c400 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1c410 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1c420 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1c430 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1c440 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1c450 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1c460 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1c470 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1c480 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1c490 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1c4a0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1c4b0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1c4c0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1c4d0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1c4e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1c4f0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1c500 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1c510 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1c520 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1c530 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c540 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1c550 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1c560 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1c570 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1c580 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1c590 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1c5a0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1c5b0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1c5c0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1c5d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1c5e0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1c5f0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1c600 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1c610 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1c620 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1c630 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1c640 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1c650 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1c660 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1c670 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1c680 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1c690 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1c6a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1c6b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1c6c0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1c6d0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1c6e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1c6f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1c700 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1c710 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1c720 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1c730 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1c740 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1c750 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1c760 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1c770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c780 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1c790 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1c7a0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1c7b0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1c7c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1c7d0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1c7e0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1c7f0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1c800 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1c810 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1c820 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1c830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1c840 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1c850 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1c860 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1c870 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1c880 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1c890 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1c8a0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1c8b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1c8c0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1c8d0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1c8e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1c8f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
1c900 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1c910 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
1c920 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1c930 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1c940 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1c950 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1c960 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c970 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1c980 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1c990 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1c9a0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1c9b0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1c9c0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1c9d0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1c9e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1c9f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1ca00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1ca10 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1ca20 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1ca30 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1ca40 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1ca50 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1ca60 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1ca70 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1ca80 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1ca90 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1caa0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1cab0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1cac0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1cad0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1cae0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1caf0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1cb00 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1cb10 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1cb20 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1cb30 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1cb40 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1cb50 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1cb60 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
1cb70 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1cb80 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1cb90 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1cba0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1cbb0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1cbc0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1cbd0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1cbe0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1cbf0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1cc00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1cc10 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1cc20 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1cc30 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1cc40 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
1cc50 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1cc60 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
1cc70 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
1cc80 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
1cc90 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
1cca0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1ccb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
1ccc0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
1ccd0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1cce0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
1ccf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1cd00 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
1cd10 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
1cd20 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
1cd30 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
1cd40 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
1cd50 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
1cd60 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
1cd70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1cd80 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
1cd90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1cda0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1cdb0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
1cdc0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1cdd0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
1cde0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
1cdf0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1ce00 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
1ce10 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
1ce20 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
1ce30 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
1ce40 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1ce50 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
1ce60 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1ce70 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1ce80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ce90 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
1cea0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
1ceb0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1cec0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
1ced0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1cee0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
1cef0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
1cf00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1cf10 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1cf20 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
1cf30 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1cf40 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
1cf50 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1cf60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1cf70 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
1cf80 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
1cf90 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
1cfa0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
1cfb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1cfc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1cfd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1cfe0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1cff0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d000 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1d010 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1d020 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1d030 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1d040 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1d050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1d060 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1d070 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1d080 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1d090 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1d0a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1d0b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1d0c0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
1d0d0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1d0e0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1d0f0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1d100 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1d110 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1d120 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1d130 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1d140 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1d150 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1d160 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1d170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d180 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1d190 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1d1a0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1d1b0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1d1c0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1d1d0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1d1e0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1d1f0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1d200 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1d210 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1d220 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1d230 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1d240 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1d250 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1d260 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1d270 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1d280 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1d290 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1d2a0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1d2b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1d2c0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1d2d0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1d2e0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d2f0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1d300 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1d310 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1d320 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1d330 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1d340 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1d350 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1d360 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d370 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1d380 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1d390 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
1d3a0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
1d3b0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
1d3c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
1d3d0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
1d3e0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1d3f0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
1d400 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1d410 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
1d420 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
1d430 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
1d440 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
1d450 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
1d460 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1d470 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
1d480 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1d490 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
1d4a0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
1d4b0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1d4c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d4d0 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
1d4e0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
1d4f0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
1d500 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
1d510 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
1d520 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
1d530 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
1d540 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
1d550 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
1d560 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1d570 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
1d580 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
1d590 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
1d5a0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1d5b0 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
1d5c0 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
1d5d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
1d5e0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
1d5f0 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
1d600 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
1d610 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
1d620 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
1d630 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
1d640 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1d650 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
1d660 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
1d670 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
1d680 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
1d690 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
1d6a0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
1d6b0 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
1d6c0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
1d6d0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
1d6e0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
1d6f0 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
1d700 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
1d710 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
1d720 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
1d730 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
1d740 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
1d750 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
1d760 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
1d770 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
1d780 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
1d790 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
1d7a0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
1d7b0 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
1d7c0 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
1d7d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
1d7e0 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
1d7f0 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
1d800 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
1d810 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
1d820 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
1d830 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
1d840 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
1d850 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
1d860 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
1d870 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
1d880 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
1d890 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
1d8a0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
1d8b0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
1d8c0 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
1d8d0 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
1d8e0 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
1d8f0 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
1d900 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
1d910 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
1d920 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
1d930 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
1d940 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
1d950 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
1d960 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
1d970 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1d980 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
1d990 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1d9a0 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
1d9b0 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
1d9c0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
1d9d0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
1d9e0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
1d9f0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
1da00 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1da10 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
1da20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
1da30 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
1da40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
1da50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
1da60 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
1da70 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
1da80 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
1da90 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
1daa0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
1dab0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
1dac0 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
1dad0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1dae0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1daf0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
1db00 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
1db10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1db20 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
1db30 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
1db40 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
1db50 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
1db60 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
1db70 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
1db80 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
1db90 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
1dba0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
1dbb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1dbc0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
1dbd0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
1dbe0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
1dbf0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
1dc00 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
1dc10 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
1dc20 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
1dc30 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
1dc40 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
1dc50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1dc60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
1dc70 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
1dc80 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
1dc90 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
1dca0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
1dcb0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f  her "ro", "rw" o
1dcc0 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20  r.**     "rwc". 
1dcd0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
1dce0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
1dcf0 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72  r value is an er
1dd00 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
1dd10 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
1dd20 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
1dd30 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1dd40 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
1dd50 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1dd60 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
1dd70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1dd80 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
1dd90 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
1dda0 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
1ddb0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ddc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e  _prepare_v2(). ^
1ddd0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
1dde0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
1ddf0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
1de00 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1de10 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
1de20 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
1de30 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
1de40 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
1de50 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1de60 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
1de70 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
1de80 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
1de90 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
1dea0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
1deb0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
1dec0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
1ded0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
1dee0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
1def0 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74  REATE. ^If sqlit
1df00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1df10 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74  .**     used, it
1df20 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
1df30 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
1df40 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72  for the mode par
1df50 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 0a  ameter that is .
1df60 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65 73 74  **     less rest
1df70 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
1df80 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
1df90 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
1dfa0 61 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a  as the third .**
1dfb0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
1dfc0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
1dfd0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
1dfe0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1dff0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
1e000 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
1e010 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
1e020 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
1e030 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
1e040 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1e050 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
1e060 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1e070 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
1e080 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
1e090 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
1e0a0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
1e0b0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
1e0c0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
1e0d0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
1e0e0 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
1e0f0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1e100 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
1e110 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
1e120 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
1e130 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e140 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
1e150 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
1e160 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
1e170 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
1e180 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
1e190 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
1e1a0 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65  haviour requeste
1e1b0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
1e1c0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
1e1d0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
1e1e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1e1f0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
1e200 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
1e210 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
1e220 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
1e230 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
1e240 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
1e250 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
1e260 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1e270 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1e280 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
1e290 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
1e2a0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
1e2b0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
1e2c0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
1e2d0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
1e2e0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
1e2f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1e300 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
1e310 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
1e320 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
1e330 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
1e340 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
1e350 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
1e360 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
1e370 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
1e380 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
1e390 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
1e3a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1e3b0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
1e3c0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1e3d0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
1e3e0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
1e3f0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
1e400 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
1e410 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1e420 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
1e430 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
1e440 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
1e450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1e460 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
1e470 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1e480 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
1e490 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
1e4a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
1e4b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1e4c0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
1e4d0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
1e4e0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1e4f0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1e500 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
1e510 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
1e520 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
1e530 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
1e540 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
1e550 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
1e560 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1e570 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
1e580 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
1e590 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
1e5a0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
1e5b0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
1e5c0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
1e5d0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
1e5e0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
1e5f0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
1e600 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
1e610 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
1e620 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
1e630 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
1e640 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
1e650 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
1e660 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
1e670 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
1e680 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
1e690 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
1e6a0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1e6b0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
1e6c0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
1e6d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
1e6e0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
1e6f0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
1e700 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
1e710 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
1e720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
1e730 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1e740 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1e750 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
1e760 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
1e770 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
1e780 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
1e790 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
1e7a0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
1e7b0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
1e7c0 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
1e7d0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
1e7e0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
1e7f0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
1e800 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
1e810 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
1e820 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
1e830 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
1e840 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
1e850 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
1e860 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
1e870 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
1e880 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
1e890 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
1e8a0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
1e8b0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
1e8c0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
1e8d0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
1e8e0 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
1e8f0 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
1e900 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
1e910 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
1e920 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
1e930 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
1e940 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
1e950 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
1e960 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
1e970 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
1e980 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
1e990 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
1e9a0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
1e9b0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
1e9c0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
1e9d0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
1e9e0 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
1e9f0 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
1ea00 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
1ea10 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
1ea20 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
1ea30 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
1ea40 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
1ea50 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
1ea60 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
1ea70 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
1ea80 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
1ea90 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
1eaa0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
1eab0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1eac0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
1ead0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1eae0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1eaf0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1eb00 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1eb10 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1eb20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1eb30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1eb40 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1eb50 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1eb60 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1eb70 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1eb80 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1eb90 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1eba0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1ebb0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1ebc0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1ebd0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1ebe0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1ebf0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1ec00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1ec10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1ec20 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1ec30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1ec40 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1ec50 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1ec60 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1ec70 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1ec80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1ec90 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1eca0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
1ecb0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1ecc0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1ecd0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1ece0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1ecf0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1ed00 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1ed10 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1ed20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ed30 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1ed40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
1ed50 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1ed60 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1ed70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1ed80 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1ed90 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1eda0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1edb0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1edc0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1edd0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1ede0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1edf0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1ee00 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1ee10 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1ee20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1ee30 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
1ee40 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
1ee50 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
1ee60 2a 20 54 68 69 73 20 69 73 20 61 20 75 74 69 6c  * This is a util
1ee70 69 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73 65  ity routine, use
1ee80 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
1ee90 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
1eea0 20 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73 65   checks.** to se
1eeb0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
1eec0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
1eed0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
1eee0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
1eef0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
1ef00 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
1ef10 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1ef20 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1ef30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69 6c  ..**.** The zFil
1ef40 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1ef50 73 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 70  s the filename p
1ef60 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
1ef70 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
1ef80 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56 46  * method of a VF
1ef90 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1efa0 2e 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61 72  .  The zParam ar
1efb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 61  gument is the na
1efc0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75 65  me of the.** que
1efd0 72 79 20 70 61 72 61 6d 65 74 65 72 20 77 65 20  ry parameter we 
1efe0 73 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75 74  seek.  This rout
1eff0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1f000 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50 61  value of the zPa
1f010 72 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ram.** parameter
1f020 20 69 66 20 69 74 20 65 78 69 73 74 73 2e 20 20   if it exists.  
1f030 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1f040 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c   does not exist,
1f050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
1f060 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1f070 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  pointer..**.** I
1f080 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
1f090 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
1f0a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
1f0b0 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
1f0c0 53 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65 64  SQLite.** passed
1f0d0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 20   into the xOpen 
1f0e0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
1f0f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
1f100 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
1f110 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f120 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
1f130 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
1f140 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
1f150 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
1f160 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
1f170 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
1f180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
1f190 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  m);.../*.** CAPI
1f1a0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1f1b0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
1f1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f1d0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1f1e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1f1f0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1f200 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1f210 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f220 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1f230 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1f240 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1f250 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1f260 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1f270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1f280 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1f290 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1f2a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1f2b0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1f2c0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1f2d0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1f2e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1f2f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
1f300 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1f310 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1f320 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1f330 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1f340 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1f350 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1f360 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f370 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1f380 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f390 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1f3a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1f3b0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1f3c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1f3d0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1f3e0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1f3f0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1f400 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1f410 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1f420 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1f430 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
1f440 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1f450 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1f460 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1f470 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1f480 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1f490 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1f4a0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1f4b0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1f4c0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1f4d0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1f4e0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1f4f0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1f500 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1f510 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1f520 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1f530 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
1f540 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
1f550 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1f560 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
1f570 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
1f580 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
1f590 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
1f5a0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
1f5b0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1f5c0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
1f5d0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
1f5e0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
1f5f0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
1f600 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
1f610 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
1f620 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
1f630 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
1f640 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
1f650 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
1f660 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
1f670 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
1f680 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
1f690 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
1f6a0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
1f6b0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
1f6c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1f6d0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
1f6e0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1f6f0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
1f700 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1f710 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
1f720 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
1f730 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
1f740 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1f750 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
1f760 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
1f770 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
1f780 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
1f790 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
1f7a0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
1f7b0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1f7c0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1f7d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1f7e0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1f7f0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1f800 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1f810 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1f820 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1f830 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1f840 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1f850 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1f860 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
1f870 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1f880 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1f890 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
1f8a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f8b0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1f8c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1f8d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
1f8e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1f8f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1f900 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1f910 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f920 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1f930 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f940 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1f950 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
1f960 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1f970 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1f980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1f990 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1f9a0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1f9b0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1f9c0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1f9d0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1f9e0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1f9f0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1fa00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1fa10 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1fa20 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1fa30 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1fa40 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1fa50 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1fa60 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1fa70 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1fa80 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1fa90 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1faa0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1fab0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1fac0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fad0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1fae0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1faf0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1fb00 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1fb10 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1fb20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fb30 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1fb40 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1fb50 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1fb60 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1fb70 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1fb80 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1fb90 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1fba0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1fbb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1fbc0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1fbd0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1fbe0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1fbf0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1fc00 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1fc10 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1fc20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1fc30 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1fc40 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1fc50 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1fc60 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1fc70 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1fc80 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1fc90 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1fca0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1fcb0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1fcc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fcd0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1fce0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
1fcf0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1fd00 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1fd10 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1fd20 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1fd30 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1fd40 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1fd50 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1fd60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1fd70 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1fd80 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1fd90 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1fda0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1fdb0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fdc0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1fdd0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1fde0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1fdf0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1fe00 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1fe10 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1fe20 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1fe30 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1fe40 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1fe50 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
1fe60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
1fe70 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
1fe80 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
1fe90 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
1fea0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
1feb0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
1fec0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
1fed0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
1fee0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
1fef0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
1ff00 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
1ff10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
1ff20 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
1ff30 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
1ff40 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
1ff50 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
1ff60 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
1ff70 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1ff80 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1ff90 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
1ffa0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
1ffb0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1ffc0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1ffd0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1ffe0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1fff0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
20000 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
20010 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
20020 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
20030 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
20040 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
20050 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
20060 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
20070 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
20080 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
20090 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
200a0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
200b0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
200c0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
200d0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
200e0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
200f0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
20100 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
20110 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
20120 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
20130 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
20140 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
20150 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
20160 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
20170 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
20180 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
20190 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
201a0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
201b0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
201c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
201d0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
201e0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
201f0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
20200 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
20210 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
20220 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
20230 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
20240 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
20250 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
20260 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
20270 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
20280 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
20290 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
202a0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
202b0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
202c0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
202d0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
202e0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
202f0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
20300 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
20310 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
20320 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
20330 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
20340 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
20350 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
20360 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
20370 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
20380 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20390 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
203a0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
203b0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
203c0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
203d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
203e0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
203f0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
20400 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
20410 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
20420 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
20430 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
20440 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
20450 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
20460 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
20470 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
20480 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
20490 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
204a0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
204b0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
204c0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
204d0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
204e0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
204f0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
20500 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
20510 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
20520 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
20530 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
20540 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
20550 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
20560 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
20570 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
20580 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
20590 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
205a0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
205b0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
205c0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
205d0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
205e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
205f0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
20600 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
20610 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
20620 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
20630 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
20640 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20650 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
20660 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20670 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
20680 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
20690 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
206a0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
206b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
206c0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
206d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
206e0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
206f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20700 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
20710 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
20720 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
20730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
20740 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
20750 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
20760 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
20770 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20780 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
20790 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
207a0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
207b0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
207c0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
207d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
207e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
207f0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
20800 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
20810 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
20820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
20830 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
20840 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
20850 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
20860 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
20870 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20880 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
20890 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
208a0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
208b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
208c0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
208d0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
208e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
208f0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
20900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20910 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
20920 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
20930 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
20940 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
20950 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
20960 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
20970 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
20980 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
20990 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
209a0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
209b0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
209c0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
209d0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
209e0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
209f0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
20a00 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
20a10 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
20a20 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
20a30 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
20a40 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
20a50 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
20a60 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
20a70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
20a80 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
20a90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20aa0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
20ab0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20ac0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20ad0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
20ae0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
20af0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
20b00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
20b10 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
20b20 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
20b30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20b40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
20b50 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
20b60 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
20b70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
20b80 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
20b90 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
20ba0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
20bb0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
20bc0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
20bd0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20be0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
20bf0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
20c00 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
20c10 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
20c20 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
20c30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20c40 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
20c50 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
20c60 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
20c70 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
20c80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20c90 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
20ca0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
20cb0 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
20cc0 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
20cd0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
20ce0 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
20cf0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20d00 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
20d10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20d20 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
20d30 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
20d40 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
20d50 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
20d60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20d70 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
20d80 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
20d90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20da0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
20db0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
20dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20dd0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
20de0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
20df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20e00 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
20e10 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
20e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20e30 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
20e40 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
20e50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20e60 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
20e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
20e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20e90 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
20ea0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
20eb0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
20ec0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
20ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20ee0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
20ef0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
20f00 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
20f10 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
20f20 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
20f30 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
20f40 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
20f50 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
20f60 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
20f70 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
20f80 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
20f90 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
20fa0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
20fb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20fc0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
20fd0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
20fe0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
20ff0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
21000 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
21010 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
21020 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
21030 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
21040 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
21050 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
21060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21070 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
21080 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
21090 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
210a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
210b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
210c0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
210d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
210e0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
210f0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
21100 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
21110 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
21120 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
21130 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
21140 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
21150 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
21160 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
21170 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
21180 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
21190 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
211a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
211b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
211c0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
211d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
211e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
211f0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
21200 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
21210 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
21220 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
21230 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
21240 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
21250 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
21260 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
21270 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
21280 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
21290 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
212a0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
212b0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
212c0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
212d0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
212e0 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
212f0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
21300 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
21310 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
21320 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
21330 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
21340 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
21350 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
21360 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
21370 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
21380 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
21390 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
213a0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
213b0 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
213c0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
213d0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
213e0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
213f0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
21400 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
21410 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
21420 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
21430 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
21440 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
21450 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
21460 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
21470 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
21480 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
21490 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
214a0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
214b0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
214c0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
214d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
214e0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
214f0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
21500 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
21510 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21520 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
21530 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
21540 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
21550 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
21560 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
21570 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
21580 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
21590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
215a0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
215b0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
215c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
215d0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
215e0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
215f0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
21600 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
21610 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
21620 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
21630 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
21640 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
21650 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
21660 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
21670 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
21680 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
21690 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
216a0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
216b0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
216c0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
216d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
216e0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
216f0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
21700 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
21710 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
21720 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
21730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
21740 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
21750 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21760 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
21770 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
21780 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21790 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
217a0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
217b0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
217c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
217d0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
217e0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
217f0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
21800 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
21810 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
21820 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
21830 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
21840 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
21850 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
21860 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
21870 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
21880 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
21890 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
218a0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
218b0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
218c0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
218d0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
218e0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
218f0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
21900 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
21910 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
21920 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
21930 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
21940 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
21950 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
21960 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
21970 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
21980 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
21990 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
219a0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
219b0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
219c0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
219d0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
219e0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
219f0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
21a00 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
21a10 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
21a20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
21a30 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
21a40 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
21a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21a60 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
21a70 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
21a80 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
21a90 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
21aa0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
21ab0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
21ac0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
21ad0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
21ae0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
21af0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
21b00 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
21b10 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
21b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
21b30 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
21b40 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
21b50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21b60 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
21b70 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
21b80 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
21b90 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
21ba0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
21bb0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
21bc0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
21bd0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
21be0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21bf0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
21c00 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
21c10 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
21c20 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
21c30 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
21c40 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
21c50 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
21c60 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
21c70 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
21c80 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
21c90 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
21ca0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
21cb0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
21cc0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
21cd0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
21ce0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
21cf0 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
21d00 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
21d10 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
21d20 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
21d30 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
21d40 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
21d50 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
21d60 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
21d70 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
21d80 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
21d90 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
21da0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
21db0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
21dc0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
21dd0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
21de0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
21df0 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
21e00 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
21e10 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
21e20 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
21e30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
21e40 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
21e50 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
21e60 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
21e70 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d  NABLE_STAT2] com
21e80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
21e90 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
21ea0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
21eb0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
21ec0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
21ed0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
21ee0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
21ef0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
21f00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
21f10 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
21f20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
21f30 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
21f40 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
21f50 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
21f60 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
21f70 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
21f80 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
21f90 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
21fa0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
21fb0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
21fc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
21fd0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
21fe0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
21ff0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22000 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
22010 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
22020 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
22030 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22040 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22050 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22060 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
22070 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
22080 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
22090 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
220a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
220b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
220c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
220d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
220e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
220f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22100 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22110 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
22120 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22130 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22140 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22150 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
22160 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22170 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
22180 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22190 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
221a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
221b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
221c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
221d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
221e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
221f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
22200 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
22210 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
22220 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
22230 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
22240 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
22250 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
22260 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
22270 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
22280 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
22290 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
222a0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
222b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
222c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
222d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
222e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
222f0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
22300 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
22310 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
22320 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
22330 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
22340 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
22350 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
22360 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
22370 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
22380 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
22390 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
223a0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
223b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
223c0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
223d0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
223e0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
223f0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
22400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22410 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
22420 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
22430 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
22440 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
22450 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
22460 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
22470 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
22480 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
22490 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
224a0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
224b0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
224c0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
224d0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
224e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
224f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22500 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
22510 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
22520 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
22530 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22540 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22550 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
22560 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
22570 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
22580 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  tabase.**.** ^Th
22590 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
225a0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
225b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
225c0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
225d0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
225e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
225f0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
22600 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
22610 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
22620 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
22630 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
22640 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
22650 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
22660 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
22670 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
22680 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
22690 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
226a0 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
226b0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
226c0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
226d0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
226e0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
226f0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
22700 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
22710 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
22720 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
22730 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
22740 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
22750 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22760 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
22770 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
22780 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
22790 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
227a0 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
227b0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
227c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
227d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
227e0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
227f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
22800 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
22810 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
22820 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
22830 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
22840 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
22850 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
22860 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
22870 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
22880 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
22890 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
228a0 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
228b0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
228c0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
228d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
228e0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
228f0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
22900 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
22910 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
22920 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
22930 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
22940 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
22950 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
22960 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
22970 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
22980 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
22990 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
229a0 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
229b0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
229c0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
229d0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
229e0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
229f0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
22a00 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
22a10 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
22a20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
22a30 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
22a40 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
22a50 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
22a60 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
22a70 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
22a80 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
22a90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
22aa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
22ab0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
22ac0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22ae0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
22af0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
22b00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
22b10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22b20 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
22b30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22b40 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
22b50 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
22b60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
22b70 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
22b80 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
22b90 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
22ba0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
22bb0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
22bc0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
22bd0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
22be0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
22bf0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
22c00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22c10 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
22c20 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
22c30 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
22c40 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
22c50 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
22c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22c70 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
22c80 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
22c90 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
22ca0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
22cb0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
22cc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22cd0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
22ce0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
22cf0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
22d00 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
22d10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22d20 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
22d30 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
22d40 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
22d50 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
22d60 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
22d70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
22d80 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
22d90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22da0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
22db0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
22dc0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
22dd0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
22de0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
22df0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
22e00 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
22e10 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
22e20 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
22e30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22e40 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
22e50 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
22e60 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
22e70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22e80 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
22e90 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
22ea0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
22eb0 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
22ec0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
22ed0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
22ee0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
22ef0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
22f00 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
22f10 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
22f20 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
22f30 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
22f40 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
22f50 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
22f60 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
22f70 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
22f80 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
22f90 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
22fa0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
22fb0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
22fc0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
22fd0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
22fe0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
22ff0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
23000 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
23010 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
23020 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
23030 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
23040 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
23050 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
23060 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
23070 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
23080 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
23090 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
230a0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
230b0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
230c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
230d0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
230e0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
230f0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
23100 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
23110 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
23120 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
23130 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
23140 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
23150 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
23160 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23170 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
23180 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23190 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
231a0 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
231b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
231c0 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
231d0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
231e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
231f0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
23200 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
23210 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
23220 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
23230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
23240 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
23250 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
23260 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
23270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23280 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
23290 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
232a0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
232b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
232c0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
232d0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
232e0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
232f0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
23300 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
23310 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
23320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
23330 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
23340 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
23350 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
23360 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
23370 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
23380 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
23390 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
233a0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
233b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
233c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
233d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
233e0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
233f0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
23400 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
23410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
23420 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
23430 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
23440 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
23450 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
23460 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
23470 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
23480 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
23490 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
234a0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
234b0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
234c0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
234d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
234e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
234f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
23500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23510 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
23520 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
23530 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
23540 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
23550 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
23560 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
23570 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
23580 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
23590 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
235a0 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
235b0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
235c0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
235d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
235e0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
235f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23600 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
23610 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
23620 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
23630 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
23640 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
23650 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
23660 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
23670 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
23680 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
23690 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
236a0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
236b0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
236c0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
236d0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
236e0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
236f0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
23700 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
23710 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
23720 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
23730 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
23740 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
23750 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
23760 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
23770 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
23780 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
23790 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
237a0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
237b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
237c0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
237d0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
237e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
237f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
23800 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
23810 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
23820 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23830 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
23840 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
23850 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
23860 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
23870 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
23880 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
23890 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
238a0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
238b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
238c0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
238d0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
238e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
238f0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
23900 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
23910 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
23920 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
23930 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
23940 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
23950 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
23960 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
23970 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
23980 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
23990 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
239a0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
239b0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
239c0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
239d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
239e0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
239f0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
23a00 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
23a10 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
23a20 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
23a30 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
23a40 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
23a50 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
23a60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
23a70 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
23a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
23a90 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
23aa0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
23ab0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
23ac0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
23ad0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
23ae0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
23af0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
23b00 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
23b10 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
23b20 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
23b30 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
23b40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23b50 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
23b60 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
23b70 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
23b80 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
23b90 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
23ba0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
23bb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
23bc0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
23bd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
23be0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
23bf0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
23c00 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
23c10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23c20 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
23c30 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
23c40 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
23c50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
23c60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
23c70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
23c80 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
23c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
23ca0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
23cb0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
23cc0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
23cd0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
23ce0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
23cf0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
23d00 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
23d10 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
23d20 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
23d30 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
23d40 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
23d50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
23d60 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
23d70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
23d80 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
23d90 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
23da0 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
23db0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
23dc0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
23dd0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
23de0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
23df0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
23e00 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
23e10 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
23e20 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
23e30 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
23e40 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
23e50 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
23e60 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
23e70 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
23e80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
23e90 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
23ea0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
23eb0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
23ec0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
23ed0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
23ee0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
23ef0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
23f00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
23f10 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
23f20 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
23f30 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
23f40 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
23f50 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
23f60 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
23f70 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
23f80 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
23f90 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
23fa0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
23fb0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
23fc0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
23fd0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
23fe0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
23ff0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
24000 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
24010 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
24020 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
24030 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
24040 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
24050 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
24060 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
24070 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
24080 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
24090 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
240a0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
240b0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
240c0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
240d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
240e0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
240f0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
24100 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
24110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24120 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
24130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24140 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
24150 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
24160 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
24170 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
24180 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
24190 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
241a0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
241b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
241c0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
241d0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
241e0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
241f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24200 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
24210 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
24220 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
24230 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24240 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
24250 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
24260 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
24270 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
24280 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
24290 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
242a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
242b0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
242c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
242d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
242e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
242f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
24300 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
24310 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
24320 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
24330 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
24340 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
24350 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24360 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
24370 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
24380 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
24390 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
243a0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
243b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
243c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
243d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
243e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
243f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
24400 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
24410 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
24420 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
24430 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24440 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
24450 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
24460 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
24470 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
24480 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
24490 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
244a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
244b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
244c0 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
244d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
244e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
244f0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
24500 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24510 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
24520 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24530 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
24540 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
24550 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24560 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
24570 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
24580 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24590 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
245a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
245b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
245c0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
245d0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
245e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
245f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
24600 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
24610 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
24620 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
24630 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24640 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
24650 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24660 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
24670 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
24680 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24690 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
246a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
246b0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
246c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
246d0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
246e0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
246f0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
24700 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
24710 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
24720 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
24730 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
24740 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
24750 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
24760 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
24770 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
24780 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
24790 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
247a0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
247b0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
247c0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
247d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
247e0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
247f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
24800 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
24810 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
24820 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
24830 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
24840 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
24850 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
24860 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
24870 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
24880 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
24890 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
248a0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
248b0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
248c0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
248d0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
248e0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
248f0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
24900 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
24910 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
24920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24930 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
24940 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
24950 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
24960 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
24970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24980 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
24990 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
249a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
249b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
249c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
249d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
249e0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
249f0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
24a00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
24a10 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
24a20 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
24a30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
24a40 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
24a50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
24a60 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
24a70 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
24a80 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
24a90 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
24aa0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
24ab0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
24ac0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
24ad0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
24ae0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
24af0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
24b00 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
24b10 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
24b20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
24b30 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
24b40 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
24b50 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
24b60 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
24b70 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
24b80 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
24b90 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
24ba0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
24bb0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
24bc0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
24bd0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
24be0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
24bf0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
24c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
24c10 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
24c20 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
24c30 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
24c40 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
24c50 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
24c60 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
24c70 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
24c80 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
24c90 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
24ca0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
24cb0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
24cc0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
24cd0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
24ce0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
24cf0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
24d00 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
24d10 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
24d20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
24d30 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
24d40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
24d50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
24d60 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
24d70 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
24d80 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
24d90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24da0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
24db0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
24dc0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
24dd0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
24de0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
24df0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24e00 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
24e10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
24e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e30 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
24e40 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
24e50 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
24e60 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
24e70 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
24e80 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
24e90 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
24ea0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
24eb0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
24ec0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
24ed0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
24ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24ef0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
24f00 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
24f10 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
24f20 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
24f30 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
24f40 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
24f50 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
24f60 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
24f70 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
24f80 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
24f90 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
24fa0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
24fb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24fc0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
24fd0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
24fe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24ff0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25000 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
25010 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25020 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
25030 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
25040 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
25050 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
25060 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
25070 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25080 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
25090 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
250a0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
250b0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
250c0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
250d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
250e0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
250f0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
25100 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
25110 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
25120 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
25130 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
25140 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
25150 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
25160 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
25170 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
25180 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
25190 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
251a0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
251b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
251c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
251d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
251e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
251f0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
25200 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
25210 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
25220 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
25230 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
25240 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
25250 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
25260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25270 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
25280 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
25290 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
252a0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
252b0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
252c0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
252d0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
252e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
252f0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
25300 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
25310 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
25320 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
25330 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25340 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25350 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
25360 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
25370 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
25380 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
25390 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
253a0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
253b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
253c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
253d0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
253e0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
253f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
25400 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
25410 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
25420 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
25430 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
25440 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
25450 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
25460 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
25470 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
25480 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
25490 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
254a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
254b0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
254c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
254d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
254e0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
254f0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
25500 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25510 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
25520 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
25530 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
25540 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
25550 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
25560 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
25570 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
25580 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
25590 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
255a0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
255b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
255c0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
255d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
255e0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
255f0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
25600 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
25610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25620 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
25630 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
25640 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
25650 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
25660 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
25670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
25680 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
25690 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
256a0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
256b0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
256c0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
256d0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
256e0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
256f0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
25700 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
25710 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
25720 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
25730 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
25740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
25750 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
25760 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
25770 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
25780 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
25790 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
257a0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
257b0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
257c0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
257d0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
257e0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
257f0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
25800 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
25810 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
25820 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
25830 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  xt..*/.SQLITE_AP
25840 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
25850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
25860 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25870 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
25880 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
25890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
258a0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
258b0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
258c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
258d0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
258e0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
258f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
25900 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
25910 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
25920 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
25930 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
25940 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
25950 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
25960 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
25970 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
25980 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
25990 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
259a0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
259b0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
259c0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
259d0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
259e0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
259f0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
25a00 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
25a10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
25a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
25a30 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
25a40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25a50 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
25a60 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
25a70 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
25a80 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
25a90 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
25aa0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
25ab0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
25ac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25ad0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
25ae0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
25af0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
25b00 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
25b10 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
25b20 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
25b30 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
25b40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25b50 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
25b60 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
25b70 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
25b80 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
25b90 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
25ba0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
25bb0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
25bc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
25bd0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
25be0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
25bf0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
25c00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
25c10 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
25c20 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
25c30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
25c40 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
25c50 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
25c60 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
25c70 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
25c80 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
25c90 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
25ca0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
25cb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
25cc0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
25cd0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
25ce0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
25cf0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
25d00 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
25d10 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
25d20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
25d30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
25d40 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
25d50 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
25d60 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
25d70 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
25d80 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
25d90 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
25da0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
25db0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
25dc0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
25dd0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
25de0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
25df0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
25e00 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
25e10 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
25e20 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
25e30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25e40 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
25e50 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
25e60 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
25e70 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
25e80 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
25e90 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
25ea0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
25eb0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
25ec0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
25ed0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
25ee0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
25ef0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
25f00 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
25f10 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
25f20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
25f30 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
25f40 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
25f50 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
25f60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
25f70 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
25f80 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
25f90 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
25fa0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
25fb0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
25fc0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
25fd0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
25fe0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
25ff0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
26000 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
26010 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
26020 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
26030 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
26040 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26050 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
26060 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
26070 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
26080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
26090 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
260a0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
260b0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
260c0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
260d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
260e0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
260f0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
26100 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
26110 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
26120 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
26130 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
26140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
26150 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
26160 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
26170 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
26180 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26190 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
261a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
261b0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
261c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
261d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
261e0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
261f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
26200 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
26210 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26220 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
26230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26240 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
26250 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
26260 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
26270 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
26280 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
26290 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
262a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
262b0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
262c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
262d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
262e0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
262f0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
26300 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
26310 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26320 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
26330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
26340 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
26350 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
26360 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
26370 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
26380 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
26390 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
263a0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
263b0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
263c0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
263d0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
263e0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
263f0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
26400 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
26410 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
26420 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
26430 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
26440 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
26450 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
26460 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
26470 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
26480 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
26490 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
264a0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
264b0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
264c0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
264d0 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
264e0 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
264f0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
26500 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
26510 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
26520 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
26530 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
26540 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
26550 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
26560 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
26570 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
26580 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
26590 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
265a0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
265b0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
265c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
265d0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
265e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
265f0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
26600 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
26610 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
26620 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
26630 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
26640 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
26650 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
26660 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
26670 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
26680 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
26690 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
266a0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
266b0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
266c0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
266d0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
266e0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
266f0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
26700 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
26710 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
26720 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
26730 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
26740 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
26750 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
26760 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
26770 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26780 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
26790 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
267a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
267b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
267c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
267d0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
267e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
267f0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
26800 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
26810 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
26820 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
26830 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
26840 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
26850 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
26860 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26870 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26880 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
26890 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
268a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
268b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
268c0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
268d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
268e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
268f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
26900 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
26910 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
26920 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
26930 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
26940 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
26950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
26960 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
26970 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
26980 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
26990 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
269a0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
269b0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
269c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
269d0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
269e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
269f0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
26a00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
26a10 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
26a20 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
26a30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26a40 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
26a50 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
26a60 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
26a70 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
26a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
26a90 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
26aa0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
26ab0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
26ac0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
26ad0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
26ae0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
26af0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
26b00 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
26b10 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
26b20 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
26b30 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
26b40 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
26b50 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
26b60 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
26b70 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
26b80 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
26b90 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
26ba0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26bb0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
26bc0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
26bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
26be0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
26bf0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
26c00 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
26c10 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
26c20 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
26c30 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
26c40 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
26c50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
26c60 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
26c70 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
26c80 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
26c90 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
26ca0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
26cb0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
26cc0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
26cd0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
26ce0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
26cf0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
26d00 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
26d10 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
26d20 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
26d30 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
26d40 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
26d50 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
26d60 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
26d70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
26d80 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
26d90 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
26da0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
26db0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
26dc0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
26dd0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
26de0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
26df0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
26e00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26e10 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
26e20 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
26e30 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
26e40 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
26e50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
26e60 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
26e70 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
26e80 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
26e90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
26ea0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
26eb0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
26ec0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
26ed0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
26ee0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
26ef0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
26f00 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
26f10 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
26f20 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
26f30 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
26f40 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
26f50 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
26f60 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
26f70 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
26f80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
26f90 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
26fa0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
26fb0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
26fc0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
26fd0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
26fe0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
26ff0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
27000 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
27010 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
27020 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
27030 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
27040 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
27050 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
27060 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
27070 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
27080 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
27090 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
270a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
270b0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
270c0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
270d0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
270e0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
270f0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
27100 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27110 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
27120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27130 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
27140 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
27150 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
27160 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
27170 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
27180 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27190 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
271a0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
271b0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
271c0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
271d0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
271e0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
271f0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
27200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27210 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
27220 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
27230 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
27240 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
27250 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
27260 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
27270 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
27280 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
27290 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
272a0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
272b0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
272c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
272d0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
272e0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
272f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
27300 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
27310 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
27320 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
27330 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
27340 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
27350 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
27360 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
27370 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
27380 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
27390 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
273a0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
273b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
273c0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
273d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
273e0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
273f0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
27400 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
27410 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
27420 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
27430 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27440 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
27450 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
27460 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
27470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
27480 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
27490 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
274a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
274b0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
274c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
274d0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
274e0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
274f0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
27500 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
27510 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
27520 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
27530 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
27540 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
27550 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
27560 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
27570 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
27580 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
27590 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
275a0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
275b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
275c0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
275d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
275e0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
275f0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
27600 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
27610 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
27620 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
27630 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
27640 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
27650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
27660 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
27670 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
27680 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
27690 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
276a0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
276b0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
276c0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
276d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
276e0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
276f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
27700 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27710 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
27720 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
27730 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
27740 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
27750 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
27760 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27770 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
27780 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
27790 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
277a0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
277b0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
277c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
277d0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
277e0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
277f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
27800 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
27810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27820 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
27830 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
27840 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
27850 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
27860 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
27870 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
27880 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
27890 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
278a0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
278b0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
278c0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
278d0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
278e0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
278f0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
27900 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
27910 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
27920 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27930 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
27940 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
27950 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
27960 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
27970 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
27980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
27990 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
279a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
279b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
279c0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
279d0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
279e0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
279f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27a00 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
27a10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27a20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
27a30 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
27a40 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
27a50 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
27a60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
27a70 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
27a80 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
27a90 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
27aa0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27ab0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
27ac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
27ad0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
27ae0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
27af0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
27b00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
27b10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
27b30 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
27b40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
27b50 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
27b60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27b80 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
27b90 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
27ba0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
27bb0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
27bc0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
27bd0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
27be0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
27bf0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
27c00 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
27c10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
27c20 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
27c30 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
27c40 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
27c50 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
27c60 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
27c70 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
27c80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
27c90 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
27ca0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
27cb0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
27cc0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
27cd0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
27ce0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
27cf0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
27d00 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
27d10 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
27d20 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
27d30 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
27d40 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
27d50 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
27d60 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
27d70 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
27d80 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
27d90 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
27da0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27db0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
27dc0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
27dd0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27de0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
27df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
27e00 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
27e10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
27e20 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
27e30 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
27e40 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
27e50 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
27e60 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
27e70 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
27e80 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
27e90 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
27ea0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
27eb0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
27ec0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
27ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
27ee0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
27ef0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
27f00 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
27f10 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
27f20 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
27f30 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
27f40 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
27f50 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
27f60 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
27f70 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
27f80 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
27f90 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
27fa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27fb0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
27fc0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
27fd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
27fe0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
27ff0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
28000 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28010 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
28020 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
28030 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
28040 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
28050 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
28060 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
28070 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
28080 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
28090 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
280a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
280b0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
280c0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
280d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
280e0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
280f0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
28100 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
28110 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
28120 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
28130 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
28140 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
28150 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
28160 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
28170 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
28180 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
28190 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
281a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
281b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
281c0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
281d0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
281e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
281f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28200 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
28210 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
28220 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
28230 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
28240 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28250 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
28260 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
28270 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
28280 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
28290 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
282a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
282b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
282c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
282d0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
282e0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
282f0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
28300 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
28310 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
28320 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28330 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
28340 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
28350 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
28370 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
28380 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
28390 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
283a0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
283b0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
283c0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
283d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
283e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
283f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
28400 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
28410 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
28420 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
28430 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
28440 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
28450 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
28460 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
28470 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
28480 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
28490 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
284a0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
284b0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
284c0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
284d0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
284e0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
284f0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
28500 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
28510 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
28520 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
28530 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
28540 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
28550 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
28560 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
28570 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
28580 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
28590 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
285a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
285b0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
285c0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
285d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
285e0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
285f0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
28600 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
28610 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
28620 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
28630 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
28640 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
28650 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
28660 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
28670 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
28680 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
28690 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
286a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
286b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
286c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
286d0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
286e0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
286f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
28700 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
28710 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
28720 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
28730 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
28740 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
28750 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
28760 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
28770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28780 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
28790 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
287a0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
287b0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
287c0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
287d0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
287e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
287f0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28810 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
28820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28830 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
28840 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
28850 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
28860 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
28870 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
28880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28890 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
288a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
288b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
288c0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
288d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
288e0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
288f0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
28900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28910 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
28920 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
28930 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
28940 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
28950 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
28960 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28970 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
28980 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
28990 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
289a0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
289b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
289c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
289d0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
289e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
289f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
28a00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28a10 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
28a20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28a30 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
28a40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28a50 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
28a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
28a70 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
28a80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28a90 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
28aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28ab0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
28ac0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
28ad0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
28ae0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
28af0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
28b00 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
28b10 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
28b20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28b30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
28b40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
28b50 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
28b60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
28b70 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
28b80 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
28b90 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
28ba0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
28bb0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
28bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28bd0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
28be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
28bf0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
28c00 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
28c10 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
28c20 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
28c30 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
28c40 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
28c50 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
28c60 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
28c70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28c80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
28c90 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
28ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28cb0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
28cc0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
28cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28ce0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
28cf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28d00 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
28d10 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28d20 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
28d30 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
28d40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
28d50 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
28d60 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
28d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28d80 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
28d90 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
28da0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
28db0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
28dc0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
28dd0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
28de0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
28df0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
28e00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
28e10 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
28e20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28e30 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
28e40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28e50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
28e60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
28e70 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
28e80 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
28e90 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
28ea0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
28eb0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
28ec0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
28ed0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
28ee0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
28ef0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
28f00 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
28f10 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
28f20 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
28f30 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
28f40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
28f50 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
28f60 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
28f70 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
28f80 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
28f90 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
28fa0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
28fb0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
28fc0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
28fd0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
28fe0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
28ff0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
29000 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
29010 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
29020 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
29030 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
29040 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29050 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29060 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
29070 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
29080 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
29090 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
290a0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
290b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
290c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
290d0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
290e0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
290f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
29100 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
29110 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
29120 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
29130 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
29140 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
29150 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
29160 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
29170 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
29180 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
29190 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
291a0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
291b0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
291c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
291d0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
291e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
291f0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
29200 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
29210 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
29220 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
29230 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
29240 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
29250 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
29260 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
29270 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
29280 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
29290 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
292a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
292b0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
292c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
292d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
292e0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
292f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
29300 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
29310 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
29320 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
29330 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
29340 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
29350 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
29360 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
29370 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
29380 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
29390 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
293a0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
293b0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
293c0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
293d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
293e0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
293f0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
29400 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
29410 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
29420 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
29430 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
29440 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
29450 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
29460 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
29470 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
29480 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
29490 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
294a0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
294b0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
294c0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
294d0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
294e0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
294f0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
29500 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
29510 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
29520 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
29530 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
29540 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
29550 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
29560 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
29570 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
29580 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
29590 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
295a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
295b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
295c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
295d0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
295e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
295f0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
29600 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
29610 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
29620 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
29630 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
29640 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
29650 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
29660 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
29670 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
29680 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
29690 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
296a0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
296b0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
296c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
296d0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
296e0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
296f0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
29700 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
29710 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
29720 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29730 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
29740 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
29750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29760 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
29770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29780 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
29790 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
297a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
297b0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
297c0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
297d0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
297e0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
297f0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
29800 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
29810 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
29820 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29830 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
29840 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
29850 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
29860 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
29870 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
29880 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
29890 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
298a0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
298b0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
298c0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
298d0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
298e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
298f0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
29900 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
29910 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
29920 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
29930 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
29940 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
29950 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
29960 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
29970 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
29980 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
29990 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
299a0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
299b0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
299c0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
299d0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
299e0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
299f0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
29a00 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
29a10 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
29a20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
29a30 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
29a40 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
29a50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
29a60 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
29a70 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
29a80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
29a90 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
29aa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
29ab0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
29ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
29ad0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29af0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
29b00 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
29b10 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
29b20 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
29b30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
29b40 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
29b50 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
29b60 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
29b70 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
29b80 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
29b90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29ba0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
29bb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29bc0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
29bd0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
29be0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
29bf0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
29c00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29c10 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
29c20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29c30 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
29c40 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
29c50 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
29c60 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
29c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29c80 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
29c90 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
29ca0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
29cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29cc0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
29cd0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
29ce0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
29cf0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
29d00 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
29d10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29d20 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
29d30 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
29d40 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
29d50 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
29d60 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
29d70 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
29d80 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
29d90 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
29da0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29db0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
29dc0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
29dd0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
29de0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
29df0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
29e00 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
29e10 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
29e20 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
29e30 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
29e40 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
29e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29e60 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
29e70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
29e80 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
29e90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
29ea0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
29eb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
29ec0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
29ed0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
29ee0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
29ef0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
29f00 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
29f10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
29f20 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
29f30 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
29f40 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
29f50 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
29f60 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
29f70 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
29f80 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
29f90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
29fa0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
29fb0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
29fc0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
29fd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
29fe0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29ff0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2a000 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2a020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a030 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2a040 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a050 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a070 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2a080 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a090 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
2a0a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2a0b0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2a0c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a0d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2a0e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a0f0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2a100 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2a110 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2a120 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2a130 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2a140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2a150 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2a160 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
2a170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a180 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2a190 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a1a0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
2a1b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2a1d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a1e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2a1f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a200 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2a210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a220 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2a230 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
2a240 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a250 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2a260 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a280 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2a290 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2a2a0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2a2b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2a2c0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2a2d0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2a2e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a2f0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2a300 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2a310 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2a320 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2a330 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2a340 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2a350 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2a360 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2a370 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2a380 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2a390 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2a3a0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2a3b0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2a3c0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2a3d0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2a3e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a3f0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2a400 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2a410 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2a420 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a430 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2a440 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a450 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2a460 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2a470 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2a480 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2a490 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2a4a0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2a4b0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2a4c0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2a4d0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2a4e0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2a4f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2a500 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2a510 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2a520 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2a530 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2a540 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2a550 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2a560 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2a570 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2a580 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2a590 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2a5a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2a5b0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2a5c0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2a5d0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2a5e0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2a5f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2a600 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2a610 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2a620 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2a630 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2a640 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2a650 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2a660 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2a670 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2a680 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2a690 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2a6a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2a6b0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2a6c0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2a6d0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2a6e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2a6f0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2a700 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2a710 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2a720 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2a730 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a740 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a750 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a760 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a770 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2a780 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2a790 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2a7a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2a7b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a7c0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2a7d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a7e0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2a7f0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2a800 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2a810 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2a820 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2a830 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2a840 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2a850 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2a860 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2a870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a880 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2a890 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2a8a0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2a8b0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2a8c0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2a8d0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2a8e0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2a8f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2a900 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2a910 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2a920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a930 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2a940 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2a950 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2a960 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2a970 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a980 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a990 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2a9a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a9b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2a9c0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2a9d0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2a9e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2a9f0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2aa00 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2aa10 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2aa20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2aa30 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2aa40 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2aa50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2aa60 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2aa70 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2aa80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2aa90 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2aaa0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2aab0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2aac0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2aad0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2aae0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2aaf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2ab00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2ab10 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2ab20 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2ab30 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2ab40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ab50 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2ab60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ab70 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
2ab80 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ab90 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2aba0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2abb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2abc0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2abd0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2abe0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2abf0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2ac00 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2ac10 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2ac20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2ac30 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2ac40 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2ac50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2ac60 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2ac70 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2ac80 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2ac90 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2aca0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2acb0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2acc0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2acd0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2ace0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2acf0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2ad00 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2ad10 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2ad20 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2ad30 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2ad40 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2ad50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ad60 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2ad70 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2ad80 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2ad90 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2ada0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2adb0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2adc0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2add0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2ade0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2adf0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2ae00 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2ae10 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2ae20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ae30 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2ae40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ae50 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2ae60 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2ae70 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2ae80 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2ae90 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2aea0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2aeb0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2aec0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2aed0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2aee0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2aef0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2af00 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2af10 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2af20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2af30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2af40 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2af50 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2af60 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2af70 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2af80 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2af90 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2afa0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2afb0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2afc0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2afd0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2afe0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2aff0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2b000 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2b010 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2b020 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2b030 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2b040 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2b050 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2b060 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2b070 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2b080 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2b090 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2b0a0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2b0b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2b0c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2b0d0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2b0e0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2b0f0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2b100 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2b110 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2b120 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2b130 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2b140 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b150 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b160 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2b170 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2b180 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2b190 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2b1a0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2b1b0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2b1c0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2b1d0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2b1e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2b1f0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2b200 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2b210 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2b220 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2b230 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2b240 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2b250 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2b260 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2b270 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2b280 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2b290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2b2a0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2b2b0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2b2c0 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
2b2d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b2e0 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
2b2f0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
2b300 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2b310 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2b320 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2b330 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2b340 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2b350 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2b360 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
2b370 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
2b380 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
2b390 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b3a0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2b3b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b3c0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2b3d0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2b3e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2b3f0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2b400 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2b410 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
2b420 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2b430 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2b440 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2b450 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2b460 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2b470 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2b480 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2b490 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2b4a0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2b4b0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2b4c0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2b4d0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2b4e0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2b4f0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2b500 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2b510 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2b520 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2b530 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2b540 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
2b550 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2b560 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2b570 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2b580 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2b590 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2b5a0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2b5b0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2b5c0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2b5d0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
2b5e0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
2b5f0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
2b600 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
2b610 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
2b620 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
2b630 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
2b640 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
2b650 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2b660 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2b670 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
2b680 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2b690 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2b6a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2b6b0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2b6c0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
2b6d0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
2b6e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2b6f0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2b700 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
2b710 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2b720 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2b730 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2b740 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
2b750 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
2b760 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
2b770 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2b780 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
2b790 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
2b7a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2b7b0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
2b7c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
2b7d0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
2b7e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
2b7f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
2b800 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
2b810 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2b820 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2b830 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
2b840 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
2b850 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
2b860 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2b870 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
2b880 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b890 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
2b8a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
2b8b0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
2b8c0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
2b8d0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
2b8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b8f0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
2b900 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2b910 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
2b920 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
2b930 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2b940 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2b950 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
2b960 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
2b970 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
2b980 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
2b990 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
2b9a0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
2b9b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
2b9c0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
2b9d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b9e0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
2b9f0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
2ba00 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
2ba10 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2ba20 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
2ba30 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
2ba40 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2ba50 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2ba60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2ba70 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2ba80 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2ba90 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2baa0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2bab0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2bac0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2bad0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2bae0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2baf0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
2bb00 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2bb10 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
2bb20 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2bb30 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2bb40 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2bb50 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2bb60 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
2bb70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2bb80 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
2bb90 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
2bba0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
2bbb0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2bbc0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2bbd0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
2bbe0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
2bbf0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2bc00 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
2bc10 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
2bc20 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
2bc30 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2bc40 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
2bc50 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2bc60 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2bc70 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2bc80 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
2bc90 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2bca0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2bcb0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
2bcc0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
2bcd0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
2bce0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2bcf0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2bd00 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2bd10 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
2bd20 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
2bd30 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
2bd40 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
2bd50 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
2bd60 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2bd70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2bd80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
2bd90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bda0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2bdb0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2bdc0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2bdd0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2bde0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2bdf0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2be00 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2be10 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2be20 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2be30 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2be40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2be50 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2be60 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2be70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2be80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2be90 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2bea0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2beb0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2bec0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2bed0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2bee0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2bef0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2bf00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2bf10 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2bf20 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2bf30 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2bf40 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2bf50 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2bf60 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2bf70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2bf80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2bf90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2bfa0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2bfb0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2bfc0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2bfd0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2bfe0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2bff0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2c000 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2c010 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c020 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c030 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c040 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2c050 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c060 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c070 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2c080 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c090 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
2c0a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2c0b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2c0c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2c0d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2c0e0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2c0f0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2c100 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2c110 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2c120 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2c130 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2c140 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2c150 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2c160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2c170 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2c180 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2c190 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2c1a0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
2c1b0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
2c1c0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2c1d0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
2c1e0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
2c1f0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
2c200 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
2c210 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
2c220 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
2c230 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
2c240 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
2c250 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2c260 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
2c270 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2c280 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
2c290 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2c2a0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
2c2b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2c2c0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
2c2d0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
2c2e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2c2f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c300 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
2c310 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
2c320 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c330 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
2c340 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
2c350 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
2c360 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c370 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
2c380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c390 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
2c3a0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
2c3b0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
2c3c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
2c3d0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
2c3e0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2c3f0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2c400 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2c410 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
2c420 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
2c430 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
2c440 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
2c450 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
2c460 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
2c470 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
2c480 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2c490 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
2c4a0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
2c4b0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
2c4c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
2c4d0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
2c4e0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
2c4f0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
2c500 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
2c510 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
2c520 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2c530 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2c540 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2c550 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
2c560 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
2c570 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2c580 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2c590 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2c5a0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2c5b0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2c5c0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2c5d0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2c5e0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2c5f0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2c600 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
2c610 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2c620 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
2c630 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2c640 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
2c650 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2c660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2c670 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2c680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
2c690 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2c6a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2c6b0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2c6c0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2c6d0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2c6e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2c6f0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2c700 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2c710 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2c720 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
2c730 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2c740 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2c750 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2c760 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2c770 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2c780 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2c790 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2c7a0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2c7b0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2c7c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2c7d0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2c7e0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2c7f0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2c800 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2c810 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2c820 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2c830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c840 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2c850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c860 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2c870 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2c880 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2c890 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2c8a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2c8b0 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2c8c0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2c8d0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2c8e0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2c8f0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2c900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c910 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2c920 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2c930 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2c940 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2c950 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2c960 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2c970 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2c980 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2c990 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2c9a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c9b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2c9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2c9d0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2c9e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c9f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2ca00 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2ca10 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2ca20 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2ca30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ca40 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2ca50 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2ca60 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2ca70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2ca80 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2ca90 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2caa0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2cab0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2cac0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2cad0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2cae0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2caf0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cb00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2cb10 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2cb20 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2cb30 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2cb40 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2cb50 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2cb60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cb70 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2cb80 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2cb90 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2cba0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2cbb0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2cbc0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2cbd0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2cbe0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2cbf0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2cc00 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2cc10 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2cc20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2cc30 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2cc40 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2cc50 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2cc60 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
2cc70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2cc80 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2cc90 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2cca0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2ccb0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2ccc0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2ccd0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2cce0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2ccf0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2cd00 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2cd10 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2cd20 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2cd30 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2cd40 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2cd50 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2cd60 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2cd70 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2cd80 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2cd90 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2cda0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2cdb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2cdc0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2cdd0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2cde0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2cdf0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2ce00 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2ce10 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2ce20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2ce30 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
2ce40 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2ce50 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2ce60 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2ce70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2ce80 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2ce90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2cea0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2ceb0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2cec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2ced0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2cee0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2cef0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2cf00 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2cf10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2cf20 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2cf30 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2cf40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cf50 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2cf60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cf70 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2cf80 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2cf90 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2cfa0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2cfb0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2cfc0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2cfd0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2cfe0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2cff0 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ters..*/.SQLITE_
2d000 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2d010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2d020 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
2d030 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
2d040 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2d050 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2d060 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2d070 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2d080 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
2d090 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2d0a0 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
2d0b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
2d0c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
2d0d0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2d0e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
2d0f0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2d100 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2d110 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2d120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2d130 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
2d140 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2d150 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
2d160 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
2d170 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
2d180 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2d190 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d1a0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2d1b0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
2d1c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2d1d0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2d1e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d1f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
2d200 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2d210 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2d220 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d230 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2d240 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2d250 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2d260 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
2d270 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2d280 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2d290 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2d2a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2d2b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d2c0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2d2d0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2d2e0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2d2f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2d300 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2d310 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2d320 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2d330 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2d340 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2d350 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2d360 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2d370 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2d380 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2d390 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2d3a0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2d3b0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2d3c0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2d3d0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2d3e0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2d3f0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2d400 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2d410 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2d420 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2d430 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2d440 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2d450 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2d460 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d470 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2d480 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2d490 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2d4a0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2d4b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2d4c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d4d0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2d4e0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2d4f0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2d500 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2d510 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2d520 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2d530 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2d540 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2d550 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2d560 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2d570 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2d580 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2d590 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2d5a0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2d5b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2d5c0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2d5d0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2d5e0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2d5f0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2d600 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2d610 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2d620 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2d630 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2d640 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2d650 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2d660 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2d670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d680 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d690 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2d6a0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2d6b0 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2d6c0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2d6d0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2d6e0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2d6f0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2d700 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2d710 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2d720 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2d730 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d740 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2d750 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2d760 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2d770 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2d780 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2d790 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2d7a0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2d7b0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2d7c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2d7d0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2d7e0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2d7f0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2d800 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2d810 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2d820 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2d830 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2d840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2d850 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2d860 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2d870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d880 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2d890 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2d8a0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2d8b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2d8c0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2d8d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2d8e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2d8f0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2d900 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2d910 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2d920 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2d930 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2d940 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2d950 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2d960 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2d970 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2d980 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2d990 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2d9a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2d9b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2d9c0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2d9d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2d9e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
2d9f0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
2da00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2da10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2da20 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2da30 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2da40 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2da50 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
2da60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2da70 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2da80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2da90 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2daa0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2dab0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2dac0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2dad0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2dae0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2daf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2db00 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2db10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2db20 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2db30 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2db40 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2db50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2db60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2db70 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2db80 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2db90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2dba0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2dbb0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2dbc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2dbd0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2dbe0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
2dbf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
2dc00 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
2dc10 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2dc20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
2dc30 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
2dc40 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
2dc50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dc60 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2dc70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2dc80 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2dc90 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
2dca0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dcb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
2dcc0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
2dcd0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2dce0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2dcf0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2dd00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dd10 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2dd20 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2dd30 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2dd40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2dd50 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2dd60 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2dd70 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65   sqlite3 *sqlite
2dd80 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2dd90 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2dda0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2ddb0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2ddc0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2ddd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2dde0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2ddf0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2de00 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2de10 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2de20 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2de30 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2de40 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2de50 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2de60 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2de70 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2de80 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2de90 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2dea0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2deb0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2dec0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2ded0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2dee0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2def0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2df00 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2df10 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2df20 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2df30 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2df40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2df50 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2df60 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2df70 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2df80 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2df90 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2dfa0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2dfb0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2dfc0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2dfd0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2dfe0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2dff0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2e000 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2e010 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2e020 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2e030 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2e040 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2e050 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2e060 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2e070 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2e080 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2e090 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2e0a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2e0b0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2e0c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e0d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
2e0e0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
2e0f0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2e100 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e110 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2e120 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2e130 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2e140 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e150 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
2e160 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2e170 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2e180 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2e190 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2e1a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2e1b0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2e1c0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2e1d0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2e1e0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2e1f0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2e200 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2e210 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e220 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2e230 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2e240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2e250 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2e260 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2e270 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
2e280 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
2e290 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
2e2a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
2e2b0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
2e2c0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
2e2d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e2e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
2e2f0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2e300 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
2e310 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
2e320 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
2e330 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
2e340 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
2e350 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
2e360 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2e370 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2e380 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2e390 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2e3a0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2e3b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2e3c0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2e3d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2e3e0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2e3f0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2e400 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2e410 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2e420 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2e430 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2e440 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2e450 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2e460 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2e470 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2e480 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2e490 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2e4a0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2e4b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
2e4c0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2e4d0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2e4e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2e4f0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2e500 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2e510 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2e520 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
2e530 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2e540 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2e550 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2e560 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2e570 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2e580 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2e590 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2e5a0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2e5b0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
2e5c0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
2e5d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2e5e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e5f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e600 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e610 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2e620 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2e630 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
2e640 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e650 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2e660 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
2e670 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
2e680 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e690 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e6a0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
2e6b0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
2e6c0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
2e6d0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
2e6e0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
2e6f0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
2e700 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
2e710 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
2e720 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
2e730 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
2e740 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
2e750 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
2e760 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2e770 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2e780 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
2e790 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2e7a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
2e7b0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
2e7c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2e7d0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
2e7e0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
2e7f0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
2e800 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
2e810 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
2e820 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20  royed.  ^The.** 
2e830 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2e840 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
2e850 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
2e860 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
2e870 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
2e880 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
2e890 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
2e8a0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
2e8b0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
2e8c0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
2e8d0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
2e8e0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
2e8f0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
2e900 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
2e910 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
2e920 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
2e930 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
2e940 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
2e950 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
2e960 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
2e970 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
2e980 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
2e990 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2e9a0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
2e9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
2e9c0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
2e9d0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2e9e0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
2e9f0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
2ea00 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
2ea10 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
2ea20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ea30 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
2ea40 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
2ea50 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
2ea60 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
2ea70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ea80 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
2ea90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
2eaa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2eab0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2eac0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ead0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
2eae0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2eaf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
2eb00 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
2eb10 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
2eb20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
2eb30 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
2eb40 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
2eb50 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
2eb60 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
2eb70 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
2eb80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
2eb90 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
2eba0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
2ebb0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2ebc0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2ebd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2ebe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2ebf0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
2ec00 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2ec10 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2ec20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ec30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2ec40 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
2ec50 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
2ec60 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
2ec70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
2ec80 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
2ec90 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
2eca0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
2ecb0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2ecc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2ecd0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2ece0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2ecf0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2ed00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ed10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ed20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2ed30 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2ed40 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2ed50 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2ed60 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2ed70 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2ed80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2ed90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2eda0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
2edb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2edc0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2edd0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2ede0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2edf0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2ee00 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2ee10 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2ee20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2ee30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ee40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2ee50 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2ee60 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
2ee70 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
2ee80 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
2ee90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2eea0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
2eeb0 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
2eec0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
2eed0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2eee0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
2eef0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
2ef00 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
2ef10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ef20 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
2ef30 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
2ef40 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
2ef50 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
2ef60 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2ef70 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
2ef80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ef90 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
2efa0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
2efb0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
2efc0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2efd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2efe0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
2eff0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
2f000 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
2f010 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f030 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2f040 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f050 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2f060 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2f070 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2f080 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2f090 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2f0a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2f0b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
2f0c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f0d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f0e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2f0f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2f100 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2f110 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2f120 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2f130 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2f140 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2f150 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2f160 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2f170 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2f180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f190 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2f1a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2f1b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2f1c0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
2f1d0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2f1e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2f1f0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
2f200 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
2f210 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
2f220 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
2f230 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
2f240 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
2f250 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
2f260 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
2f270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f280 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2f290 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
2f2a0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
2f2b0 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
2f2c0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
2f2d0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
2f2e0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
2f2f0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
2f300 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
2f310 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
2f320 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
2f330 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2f340 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2f350 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2f360 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2f370 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2f380 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2f390 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
2f3a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f3b0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
2f3c0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2f3d0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2f3e0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2f3f0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
2f400 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
2f410 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
2f420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f430 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2f440 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2f450 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2f460 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2f470 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2f480 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2f490 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
2f4a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f4b0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
2f4c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2f4d0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2f4e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f4f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f500 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
2f510 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2f520 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2f530 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2f540 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
2f550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2f560 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
2f570 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2f580 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2f590 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f5a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f5b0 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
2f5c0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2f5d0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2f5e0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2f5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f600 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2f610 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f620 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2f630 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2f640 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f650 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
2f660 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2f670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f680 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
2f690 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
2f6a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2f6b0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
2f6c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2f6d0 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
2f6e0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
2f6f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
2f700 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f710 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f720 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
2f730 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
2f740 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
2f750 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
2f760 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2f770 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
2f780 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
2f790 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
2f7a0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
2f7b0 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
2f7c0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
2f7d0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
2f7e0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
2f7f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2f800 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
2f810 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2f820 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
2f830 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2f840 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2f850 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2f860 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
2f870 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
2f880 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
2f890 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
2f8a0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
2f8b0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2f8c0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2f8d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2f8e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f8f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f900 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2f910 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
2f920 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
2f930 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
2f940 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
2f950 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
2f960 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
2f970 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
2f980 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
2f990 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
2f9a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
2f9b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2f9c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f9d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f9e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2f9f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2fa00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2fa10 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2fa20 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2fa30 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2fa40 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2fa50 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2fa60 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2fa70 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2fa80 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2fa90 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2faa0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2fab0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fad0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
2fae0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
2faf0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2fb00 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2fb10 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
2fb20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
2fb30 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2fb40 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2fb50 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
2fb60 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
2fb70 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
2fb80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2fb90 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
2fba0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
2fbb0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
2fbc0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
2fbd0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
2fbe0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
2fbf0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2fc00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fc10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fc20 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fc30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fc40 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2fc50 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2fc60 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
2fc70 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
2fc80 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2fc90 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
2fca0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
2fcb0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
2fcc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
2fcd0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
2fce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fcf0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2fd00 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2fd10 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
2fd20 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2fd30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fd40 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
2fd50 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
2fd60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2fd70 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
2fd80 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
2fd90 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
2fda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2fdb0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2fdc0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
2fdd0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
2fde0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
2fdf0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
2fe00 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
2fe10 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
2fe20 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
2fe30 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
2fe40 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2fe50 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2fe60 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
2fe70 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
2fe80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2fe90 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
2fea0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
2feb0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
2fec0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fed0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
2fee0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
2fef0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
2ff00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2ff10 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
2ff20 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
2ff30 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
2ff40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ff50 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2ff60 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
2ff70 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
2ff80 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
2ff90 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
2ffa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ffb0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
2ffc0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
2ffd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2ffe0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
2fff0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
30000 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
30010 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
30020 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
30030 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
30040 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
30050 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30060 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
30070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
30080 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
30090 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
300a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
300b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
300c0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
300d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
300e0 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
300f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
30100 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30110 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
30120 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
30130 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
30140 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
30150 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
30160 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
30170 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
30180 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
30190 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
301a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
301b0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
301c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
301d0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
301e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
301f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
30200 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
30210 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
30220 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
30230 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
30240 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30250 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
30260 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
30270 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
30280 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
30290 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
302a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
302b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
302c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
302d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
302e0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
302f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30300 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
30310 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
30320 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
30330 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30340 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
30350 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
30360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
30370 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30380 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
30390 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
303a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
303b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
303c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
303d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
303e0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
303f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
30400 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
30410 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
30420 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
30430 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30440 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30450 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
30460 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
30470 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30480 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
30490 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
304a0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
304b0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
304c0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
304d0 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
304e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
304f0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
30500 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
30510 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
30520 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
30530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
30540 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
30550 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
30560 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
30570 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
30580 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
30590 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
305a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
305b0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
305c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
305d0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
305e0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
305f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30600 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
30610 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
30620 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
30630 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
30640 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
30650 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
30660 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
30670 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
30680 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
30690 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
306a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
306b0 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
306c0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
306d0 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
306e0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
306f0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
30700 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
30710 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
30720 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
30730 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
30740 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
30750 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
30760 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
30770 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
30780 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
30790 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
307a0 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
307b0 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
307c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
307d0 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
307e0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
307f0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
30800 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
30810 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
30820 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
30830 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
30840 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
30850 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30860 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
30870 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
30880 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
30890 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
308a0 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
308b0 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
308c0 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
308d0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
308e0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
308f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30900 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
30910 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
30920 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
30930 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
30940 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30950 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
30960 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
30970 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
30980 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
30990 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
309a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
309b0 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
309c0 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
309d0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
309e0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
309f0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
30a00 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
30a10 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
30a20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
30a30 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
30a40 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
30a50 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
30a60 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
30a70 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
30a80 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
30a90 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
30aa0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
30ab0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
30ac0 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
30ad0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
30ae0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
30af0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
30b00 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
30b10 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
30b20 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
30b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
30b40 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
30b50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
30b60 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
30b70 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
30b80 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
30b90 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
30ba0 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
30bb0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
30bc0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
30bd0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
30be0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
30bf0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
30c00 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
30c10 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
30c20 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
30c30 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
30c40 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
30c50 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
30c60 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
30c70 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
30c80 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
30c90 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
30ca0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
30cb0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
30cc0 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
30cd0 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
30ce0 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
30cf0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
30d00 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
30d10 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
30d20 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
30d30 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
30d40 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
30d50 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
30d60 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
30d70 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
30d80 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
30d90 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
30da0 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
30db0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
30dc0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
30dd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
30de0 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
30df0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
30e00 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
30e10 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
30e20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
30e30 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
30e40 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
30e50 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
30e60 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
30e70 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
30e80 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
30e90 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
30ea0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
30eb0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
30ec0 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
30ed0 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
30ee0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
30ef0 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
30f00 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
30f10 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
30f20 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
30f30 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
30f40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
30f50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
30f60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30f70 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
30f80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30f90 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
30fa0 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
30fb0 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
30fc0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
30fd0 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
30fe0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
30ff0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
31000 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
31010 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
31020 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
31030 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
31040 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
31050 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
31060 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
31070 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
31080 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
31090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
310a0 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
310b0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
310c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
310d0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
310e0 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
310f0 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
31100 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31110 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
31120 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
31130 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
31140 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
31150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31160 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
31170 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
31180 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
31190 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
311a0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
311b0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
311c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
311d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
311e0 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
311f0 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
31200 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
31210 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
31220 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
31230 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
31240 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
31250 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
31260 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
31270 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
31280 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
31290 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
312a0 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
312b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
312c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
312d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
312e0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
312f0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
31300 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
31310 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31320 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31330 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
31340 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
31350 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31360 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31370 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
31380 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
31390 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
313a0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
313b0 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54   void*).);.SQLIT
313c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
313d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
313e0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
313f0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
31400 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
31410 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
31420 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
31430 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
31440 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
31450 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
31460 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
31470 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  oy)(void*).);.SQ
31480 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31490 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
314a0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
314b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
314c0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
314d0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
314e0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
314f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
31500 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
31510 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
31520 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
31530 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
31540 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
31550 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
31560 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
31570 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
31580 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
31590 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
315a0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
315b0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
315c0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
315d0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
315e0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
315f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
31600 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
31610 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
31620 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
31630 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
31640 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
31650 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
31660 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
31670 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
31680 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
31690 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
316a0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
316b0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
316c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
316d0 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
316e0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
316f0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
31700 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
31710 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
31720 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
31730 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
31740 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
31750 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
31760 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
31770 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
31780 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
31790 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
317a0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
317b0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
317c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
317d0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
317e0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
317f0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
31800 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
31810 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
31820 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
31830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
31840 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
31850 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
31860 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
31870 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
31880 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
31890 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
318a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
318b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
318c0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
318d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
318e0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
318f0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
31900 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
31910 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
31920 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
31930 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
31940 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
31950 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
31960 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
31970 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
31980 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
31990 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
319a0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
319b0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
319c0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
319d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
319e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
319f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
31a00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
31a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31a20 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  ion_v2()]..*/.SQ
31a30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31a40 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31a50 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
31a60 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
31a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
31a80 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
31a90 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
31aa0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
31ab0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
31ac0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
31ad0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
31ae0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
31af0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
31b00 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
31b10 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
31b20 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
31b30 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
31b40 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
31b50 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
31b60 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
31b70 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
31b80 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
31b90 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
31ba0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
31bb0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
31bc0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
31bd0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
31be0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
31bf0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
31c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31c10 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
31c20 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
31c30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31c40 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
31c50 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
31c60 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
31c70 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
31c80 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
31c90 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
31ca0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
31cb0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
31cc0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
31cd0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
31ce0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
31cf0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
31d00 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
31d10 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
31d20 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
31d30 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
31d40 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
31d50 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
31d60 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
31d70 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
31d80 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
31d90 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
31da0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b   int sqlite3_rek
31db0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
31dc0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
31dd0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
31de0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
31df0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
31e00 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
31e10 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
31e20 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
31e30 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
31e40 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
31e50 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
31e60 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
31e70 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
31e80 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
31e90 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49  ll work..*/.SQLI
31ea0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
31eb0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
31ec0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
31ed0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
31ee0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
31ef0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
31f00 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
31f10 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
31f20 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
31f30 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
31f40 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
31f50 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
31f60 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
31f70 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
31f80 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
31f90 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ork..*/.SQLITE_A
31fa0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
31fb0 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
31fc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
31fd0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
31fe0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
31ff0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
32000 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
32010 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
32020 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
32030 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65  t Time.**.** The
32040 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
32050 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
32060 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
32070 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
32080 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
32090 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
320a0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
320b0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
320c0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
320d0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
320e0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
320f0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
32100 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
32110 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
32120 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
32130 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
32140 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
32150 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
32160 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
32170 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
32180 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
32190 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
321a0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
321b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
321c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
321d0 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65  ** ^SQLite imple
321e0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
321f0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
32200 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
32210 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
32220 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
32230 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  fs] object.  If 
32240 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
32250 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65  hod.** of the de
32260 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74  fault VFS is not
32270 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72   implemented cor
32280 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69  rectly, or not i
32290 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a  mplemented at.**
322a0 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62   all, then the b
322b0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
322c0 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64  e3_sleep() may d
322d0 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20  eviate from the 
322e0 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69  description.** i
322f0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
32300 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51  aragraphs..*/.SQ
32310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32320 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
32330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32340 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
32350 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
32360 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
32370 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
32380 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
32390 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
323a0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
323b0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
323c0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
323d0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
323e0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
323f0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
32400 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
32410 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
32420 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
32430 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
32440 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
32450 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
32460 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
32470 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
32480 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
32490 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
324a0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
324b0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
324c0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
324d0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
324e0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
324f0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
32500 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
32510 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
32520 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
32530 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
32540 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
32550 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
32560 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
32570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
32580 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
32590 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
325a0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
325b0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
325c0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
325d0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
325e0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
325f0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
32600 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
32610 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
32620 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
32630 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
32640 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
32650 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
32660 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
32670 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
32680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
32690 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
326a0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
326b0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
326c0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
326d0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
326e0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
326f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
32700 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
32710 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
32720 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32730 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
32740 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
32750 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
32760 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
32770 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
32780 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
32790 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
327a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
327b0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
327c0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
327d0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
327e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
327f0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
32800 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
32810 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
32820 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
32830 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
32840 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
32850 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
32860 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
32870 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
32880 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
32890 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
328a0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
328b0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
328c0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
328d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
328e0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
328f0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
32900 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
32910 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
32920 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
32930 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
32940 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
32950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32960 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
32970 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
32980 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
32990 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
329a0 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
329b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
329c0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
329d0 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
329e0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
329f0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
32a00 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
32a10 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
32a20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
32a30 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
32a40 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
32a50 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
32a60 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
32a70 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
32a80 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
32a90 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
32aa0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
32ab0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
32ac0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
32ad0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
32ae0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
32af0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
32b00 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
32b10 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
32b20 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
32b30 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
32b40 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
32b50 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
32b60 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
32b70 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
32b80 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
32b90 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
32ba0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
32bb0 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
32bc0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
32bd0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
32be0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
32bf0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
32c00 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
32c10 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
32c20 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
32c30 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
32c40 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
32c50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
32c60 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
32c70 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
32c80 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
32c90 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
32ca0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
32cb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32cc0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
32cd0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
32ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
32cf0 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
32d00 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
32d10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
32d20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32d30 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
32d40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
32d50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32d60 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
32d70 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
32d80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32d90 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20   belongs.  ^The 
32da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32db0 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
32dc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
32dd0 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
32de0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
32df0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74  nection].** that
32e00 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
32e10 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
32e20 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
32e30 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
32e40 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
32e50 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
32e60 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
32e70 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
32e80 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a  first place..*/.
32e90 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
32ea0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
32eb0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
32ec0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
32ed0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
32ee0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
32ef0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
32f00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
32f10 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
32f20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
32f30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32f40 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
32f50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32f60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32f70 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
32f80 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
32f90 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
32fa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32fb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
32fc0 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
32fd0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
32fe0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
32ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33000 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
33010 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
33020 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
33030 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
33040 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
33050 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
33060 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
33070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33080 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
33090 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
330a0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
330b0 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
330c0 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
330d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
330e0 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
330f0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
33100 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
33110 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33120 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
33130 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
33140 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
33150 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
33160 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33170 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
33180 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
33190 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
331a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
331b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
331c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
331d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
331e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
331f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
33200 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
33210 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
33220 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
33230 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
33240 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
33250 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
33260 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
33270 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
33280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
33290 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
332a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
332b0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
332c0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
332d0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
332e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
332f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
33300 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
33310 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
33320 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
33330 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
33340 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
33350 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
33360 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
33370 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
33380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33390 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
333a0 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
333b0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
333c0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
333d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
333e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
333f0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
33400 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
33410 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
33420 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
33430 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
33440 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
33450 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33460 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
33470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
33480 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
33490 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
334a0 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
334b0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
334c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
334d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
334e0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
334f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33500 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
33510 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
33520 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
33530 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
33540 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
33550 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
33560 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
33570 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
33580 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
33590 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
335a0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
335b0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
335c0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
335d0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
335e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
335f0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
33600 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
33610 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
33620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
33630 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
33640 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
33650 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
33660 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
33670 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
33680 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
33690 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
336a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
336b0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
336c0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
336d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
336e0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
336f0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
33700 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
33710 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
33720 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
33730 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
33740 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
33750 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
33760 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
33770 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
33780 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
33790 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
337a0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
337b0 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
337c0 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
337d0 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
337e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
337f0 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
33800 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
33810 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
33820 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
33830 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
33840 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
33850 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
33860 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
33870 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
33880 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
33890 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
338a0 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
338b0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
338c0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
338d0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
338e0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
338f0 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
33900 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
33910 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
33920 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
33930 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
33940 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
33950 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
33960 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
33970 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
33980 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
33990 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
339a0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
339b0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
339c0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
339d0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
339e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
339f0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
33a00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
33a10 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
33a20 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61  _hook()] interfa
33a30 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ce..*/.SQLITE_AP
33a40 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
33a50 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
33a60 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
33a70 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  d*), void*);.SQL
33a80 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
33a90 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
33aa0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
33ab0 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
33ac0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
33ad0 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
33ae0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
33af0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
33b00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
33b10 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
33b20 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
33b30 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
33b40 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
33b50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33b60 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64  tion] identified
33b70 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
33b80 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  gument.** to be 
33b90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
33ba0 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
33bb0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
33bc0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  eleted..** ^Any 
33bd0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
33be0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
33bf0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
33c00 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
33c10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33c20 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
33c30 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  en..**.** ^The s
33c40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
33c50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
33c60 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
33c70 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20  nvoke when a.** 
33c80 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
33c90 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
33ca0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ted..** ^The fir
33cb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
33cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
33cd0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
33ce0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
33cf0 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
33d00 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65  _hook()..** ^The
33d10 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
33d20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
33d30 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
33d40 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
33d50 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
33d60 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
33d70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
33d80 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
33d90 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
33da0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
33db0 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  d..** ^The third
33dc0 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
33dd0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
33de0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
33df0 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  inters to the.**
33e00 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
33e10 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
33e20 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
33e30 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69   row..** ^The fi
33e40 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
33e50 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72  ameter is the [r
33e60 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77  owid] of the row
33e70 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73  ..** ^In the cas
33e80 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
33e90 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77  this is the [row
33ea0 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70  id] after the up
33eb0 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  date takes place
33ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70  ..**.** ^(The up
33ed0 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
33ee0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
33ef0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
33f00 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
33f10 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
33f20 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
33f30 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e  ite_sequence).)^
33f40 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  .**.** ^In the c
33f50 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
33f60 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74  ation, the updat
33f70 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74  e hook.** is not
33f80 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75   invoked when du
33f90 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61  plication rows a
33fa0 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75  re deleted becau
33fb0 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20  se of an.** [ON 
33fc0 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f  CONFLICT | ON CO
33fd0 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20  NFLICT REPLACE] 
33fe0 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73  clause.  ^Nor is
33ff0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
34000 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  .** invoked when
34010 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
34020 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75  d using the [tru
34030 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
34040 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65  on]..** The exce
34050 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69  ptions defined i
34060 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
34070 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
34080 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
34090 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
340a0 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
340b0 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61   hook implementa
340c0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
340d0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
340e0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
340f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34100 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
34110 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
34120 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ok.  Any actions
34130 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
34140 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34150 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
34160 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
34170 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
34180 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
34190 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
341a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
341b0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
341c0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
341d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
341e0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
341f0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
34200 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
34210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34220 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
34230 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
34240 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
34250 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ph..**.** ^The s
34260 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
34270 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
34280 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  on.** returns th
34290 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
342a0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
342b0 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  all.** on the sa
342c0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
342d0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
342e0 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
342f0 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a  irst call on D..
34300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
34310 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
34320 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
34330 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
34340 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
34350 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  rfaces..*/.SQLIT
34360 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
34370 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34380 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34390 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
343a0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
343b0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
343c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
343d0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
343e0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
343f0 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
34400 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
34410 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
34420 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
34430 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
34440 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
34450 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
34460 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
34470 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
34480 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
34490 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
344a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
344b0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
344c0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
344d0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
344e0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
344f0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
34500 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
34510 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
34520 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
34530 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
34540 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
34550 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
34560 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
34570 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
34580 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
34590 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
345a0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
345b0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
345c0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
345d0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
345e0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
345f0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
34600 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
34610 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
34620 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
34630 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
34640 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
34650 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34660 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
34670 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
34680 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
34690 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
346a0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
346b0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
346c0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
346d0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
346e0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
346f0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
34700 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
34710 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
34720 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34730 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
34740 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
34750 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
34760 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
34770 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
34780 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
34790 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
347a0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
347b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
347c0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
347d0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
347e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
347f0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
34800 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
34810 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
34820 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
34830 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
34840 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
34850 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
34860 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
34870 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45   Mode].*/.SQLITE
34880 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34890 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
348a0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
348b0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
348c0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
348d0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
348e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
348f0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
34900 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
34910 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
34920 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
34930 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
34940 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
34950 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
34960 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
34970 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
34980 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
34990 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
349a0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
349b0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
349c0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
349d0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
349e0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
349f0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
34a00 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
34a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34a20 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
34a30 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
34a40 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
34a50 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
34a60 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
34a70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
34a80 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
34a90 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
34aa0 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
34ab0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
34ac0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
34ad0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
34ae0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
34af0 4e 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  NT]..*/.SQLITE_A
34b00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
34b10 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
34b20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34b30 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
34b40 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
34b50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34b60 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
34b70 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  mit64() interfac
34b80 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75  e sets and/or qu
34b90 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66  eries the.** sof
34ba0 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  t limit on the a
34bb0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
34bc0 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
34bd0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
34be0 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  Lite..** ^SQLite
34bf0 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70   strives to keep
34c00 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69   heap memory uti
34c10 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74  lization below t
34c20 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20  he soft heap.** 
34c30 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e  limit by reducin
34c40 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  g the number of 
34c50 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68  pages held in th
34c60 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20  e page cache.** 
34c70 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75  as heap memory u
34c80 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73  sages approaches
34c90 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
34ca0 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
34cb0 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65  mit is "soft" be
34cc0 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67  cause even thoug
34cd0 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73  h SQLite strives
34ce0 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f   to stay.** belo
34cf0 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20  w the limit, it 
34d00 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20  will exceed the 
34d10 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61  limit rather tha
34d20 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e  n generate.** an
34d30 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
34d40 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72  error.  In other
34d50 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74   words, the soft
34d60 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20   heap limit .** 
34d70 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
34d90 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
34da0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
34db0 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68  _limit64() is th
34dc0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
34dd0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34de0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
34df0 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67  ll.  ^If the arg
34e00 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74  ument N is negat
34e10 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63  ive.** then no c
34e20 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f  hange is made to
34e30 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
34e40 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68  imit.  Hence, th
34e50 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a  e current.** siz
34e60 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65  e of the soft he
34e70 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20  ap limit can be 
34e80 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e  determined by in
34e90 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
34ea0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34eb0 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67  t64() with a neg
34ec0 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ative argument..
34ed0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
34ee0 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f  gument N is zero
34ef0 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68   then the soft h
34f00 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73  eap limit is dis
34f10 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  abled..**.** ^(T
34f20 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
34f30 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63  it is not enforc
34f40 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ed in the curren
34f50 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
34f60 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f  .** if one or mo
34f70 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20  re of following 
34f80 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74  conditions are t
34f90 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rue:.**.** <ul>.
34fa0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74  ** <li> The soft
34fb0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73   heap limit is s
34fc0 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c  et to zero..** <
34fd0 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75  li> Memory accou
34fe0 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  nting is disable
34ff0 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e  d using a combin
35000 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
35010 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
35020 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
35030 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c  NFIG_MEMSTATUS],
35040 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20  ...) start-time 
35050 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  option and.**   
35060 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44     the [SQLITE_D
35070 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
35080 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
35090 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41  ption..** <li> A
350a0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61  n alternative pa
350b0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
350c0 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69  ntation is speci
350d0 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  fied using.**   
350e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
350f0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
35100 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e  IG_PCACHE],...).
35110 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67  .** <li> The pag
35120 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65  e cache allocate
35130 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d  s from its own m
35140 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c  emory pool suppl
35150 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b  ied.**      by [
35160 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
35170 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
35180 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72  AGECACHE],...) r
35190 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  ather than.**   
351a0 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70     from the heap
351b0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ..** </ul>)^.**.
351c0 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  ** Beginning wit
351d0 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
351e0 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74   3.7.3, the soft
351f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
35200 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72  nforced.** regar
35210 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
35220 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
35230 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
35240 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a  Y_MANAGEMENT].**
35250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
35260 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
35270 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45    With [SQLITE_E
35280 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
35290 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65  AGEMENT],.** the
352a0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
352b0 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20   is enforced on 
352c0 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  every memory all
352d0 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75  ocation.  Withou
352e0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  t.** [SQLITE_ENA
352f0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
35300 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74  EMENT], the soft
35310 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f   heap limit is o
35320 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20  nly enforced.** 
35330 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61  when memory is a
35340 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20  llocated by the 
35350 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73  page cache.  Tes
35360 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68  ting suggests th
35370 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68  at because.** th
35380 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20  e page cache is 
35390 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20  the predominate 
353a0 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53  memory user in S
353b0 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61  QLite, most.** a
353c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c  pplications will
353d0 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74   achieve adequat
353e0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
353f0 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69  t enforcement wi
35400 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65  thout.** the use
35410 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   of [SQLITE_ENAB
35420 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
35430 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MENT]..**.** The
35440 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75   circumstances u
35450 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74  nder which SQLit
35460 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74  e will enforce t
35470 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35480 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65  it may.** change
35490 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
354a0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
354b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
354c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
354d0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
354e0 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e  mit64(sqlite3_in
354f0 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t64 N);../*.** C
35500 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
35510 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69  ted Soft Heap Li
35520 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  mit Interface.**
35530 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
35540 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72  * This is a depr
35550 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f  ecated version o
35560 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
35570 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
35580 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
35590 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
355a0 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
355b0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
355c0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79  tibility.** only
355d0 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69  .  All new appli
355e0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75  cations should u
355f0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
35600 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35610 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63  it64()] interfac
35620 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68  e rather than th
35630 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54  is one..*/.SQLIT
35640 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
35650 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
35660 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
35670 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f  imit(int N);.../
35680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
35690 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
356a0 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
356b0 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
356c0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
356d0 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
356e0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
356f0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
35700 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
35710 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
35720 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
35730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35740 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
35750 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
35760 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
35770 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  t..**.** ^The co
35780 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
35790 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
357a0 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
357b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
357c0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
357d0 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  n. ^The second p
357e0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
357f0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
35800 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
35810 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
35820 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63  mp", or an attac
35830 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
35840 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
35850 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
35860 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20  or NULL. ^If it 
35870 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
35880 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
35890 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
358a0 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
358b0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
358c0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
358d0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
358e0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
358f0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
35900 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
35910 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  es..**.** ^The t
35920 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
35930 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
35940 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
35950 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
35960 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
35970 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
35980 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
35990 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
359a0 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
359b0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
359c0 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73  .** ^Metadata is
359d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
359e0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
359f0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
35a00 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
35a10 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
35a20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
35a30 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41  his function. ^A
35a40 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75  ny of these argu
35a50 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20  ments may be.** 
35a60 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
35a70 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
35a80 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
35a90 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69   metadata is omi
35aa0 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62  tted..**.** ^(<b
35ab0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
35ac0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
35ad0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
35ae0 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
35af0 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
35b00 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
35b10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
35b20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
35b30 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
35b40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
35b50 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
35b60 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
35b70 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
35b80 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
35b90 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
35ba0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
35bb0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
35bc0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
35bd0 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
35be0 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
35bf0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
35c00 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
35c10 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
35c20 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
35c30 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
35c40 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
35c50 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
35c60 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
35c70 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
35c80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
35c90 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
35ca0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35cb0 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
35cc0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
35cd0 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72  or the.** declar
35ce0 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
35cf0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
35d00 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
35d10 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
35d20 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51  * call to any SQ
35d30 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  Lite API functio
35d40 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
35d50 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
35d60 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
35d70 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
35d80 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
35d90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35da0 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
35db0 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
35dc0 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
35dd0 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
35de0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
35df0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
35e00 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
35e10 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
35e20 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
35e30 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
35e40 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
35e50 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e  clared column. ^
35e60 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a  (If there is no.
35e70 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
35e80 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
35e90 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
35ea0 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
35eb0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
35ec0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
35ed0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
35ee0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
35ef0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
35f00 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
35f10 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
35f20 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
35f30 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
35f40 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
35f50 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
35f60 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  t: 0.** </pre>)^
35f70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
35f80 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
35f90 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
35fa0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
35fb0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
35fc0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
35fd0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
35fe0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
35ff0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
36000 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
36010 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
36020 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
36030 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
36040 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
36050 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
36060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36070 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
36080 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
36090 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a  _errmsg()).)^.**
360a0 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73  .** ^This API is
360b0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
360c0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
360d0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
360e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
360f0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
36100 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
36110 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
36120 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
36130 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36140 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
36150 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
36160 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36170 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
36180 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
36190 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
361a0 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
361b0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
361c0 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
361d0 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
361e0 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
361f0 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
36200 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
36210 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
36220 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
36230 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
36240 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
36250 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
36260 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
36270 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
36280 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
36290 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
362a0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
362b0 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20  *pNotNull,      
362c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
362d0 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e  T: True if NOT N
362e0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65  ULL constraint e
362f0 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a  xists */.  int *
36300 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20  pPrimaryKey,    
36310 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
36320 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
36330 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20   part of PK */. 
36340 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20   int *pAutoinc  
36350 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36360 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
36370 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69  column is auto-i
36380 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a  ncrement */.);..
36390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
363a0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
363b0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  n.**.** ^This in
363c0 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e  terface loads an
363d0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
363e0 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74  n library from t
363f0 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a  he named file..*
36400 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36410 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
36420 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
36430 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
36440 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e  .** SQLite exten
36450 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
36460 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
36470 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  le zFile..**.** 
36480 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74  ^The entry point
36490 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a   is zProc..** ^z
364a0 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69  Proc may be 0, i
364b0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
364c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
364d0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61  ry point.** defa
364e0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
364f0 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
36500 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36510 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
36520 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
36530 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
36540 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
36550 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  nd [SQLITE_ERROR
36560 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  ] if something g
36570 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49  oes wrong..** ^I
36580 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
36590 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
365a0 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
365b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  e.** [sqlite3_lo
365c0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
365d0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
365e0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69  attempt to.** fi
365f0 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
36600 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  h error message 
36610 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
36620 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65  emory.** obtaine
36630 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36640 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63  malloc()]. The c
36650 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a  alling function.
36660 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  ** should free t
36670 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
36680 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
36690 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45  ree()]..**.** ^E
366a0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
366b0 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
366c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
366d0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
366e0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
366f0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
36700 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77  s API,.** otherw
36710 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c  ise an error wil
36720 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
36730 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
36740 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
36750 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  n() SQL function
36760 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
36770 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61   int sqlite3_loa
36780 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
36790 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
367a0 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
367b0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
367c0 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
367d0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
367e0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
367f0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36800 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
36810 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
36820 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
36830 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
36840 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
36850 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
36860 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
36870 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
36880 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
36890 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
368a0 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
368b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
368c0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
368d0 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
368e0 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73  ing.**.** ^So as
368f0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
36900 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
36910 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
36920 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
36930 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
36940 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
36950 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
36960 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
36970 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
36980 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
36990 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
369a0 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
369b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
369c0 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  * is provided to
369d0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
369e0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
369f0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
36a00 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a  n and off..**.**
36a10 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
36a20 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65  ing is off by de
36a30 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65  fault. See ticke
36a40 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c  t #1863..** ^Cal
36a50 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
36a60 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
36a70 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69  ion() routine wi
36a80 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74  th onoff==1.** t
36a90 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
36aa0 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20   loading on and 
36ab0 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
36ac0 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a  ff==0 to turn.**
36ad0 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
36ae0 69 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  in..*/.SQLITE_AP
36af0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  I int sqlite3_en
36b00 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
36b10 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
36b20 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
36b30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
36b40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
36b50 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b   Statically Link
36b60 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a  ed Extensions.**
36b70 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
36b80 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ace causes the x
36b90 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e  EntryPoint() fun
36ba0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
36bb0 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ked for.** each 
36bc0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
36bd0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69  nnection] that i
36be0 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
36bf0 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61  idea here is tha
36c00 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  t.** xEntryPoint
36c10 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20  () is the entry 
36c20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74  point for a stat
36c30 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51  ically linked SQ
36c40 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a  Lite extension.*
36c50 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20  * that is to be 
36c60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f  automatically lo
36c70 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65  aded into all ne
36c80 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
36c90 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ctions..**.** ^(
36ca0 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20  Even though the 
36cb0 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79  function prototy
36cc0 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45  pe shows that xE
36cd0 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65  ntryPoint() take
36ce0 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74  s.** no argument
36cf0 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f  s and returns vo
36d00 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  id, SQLite invok
36d10 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  es xEntryPoint()
36d20 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61   with three.** a
36d30 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70  rguments and exp
36d40 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72  ects and integer
36d50 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68   result as if th
36d60 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74  e signature of t
36d70 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e  he.** entry poin
36d80 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f  t where as follo
36d90 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
36da0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26  quote><pre>.** &
36db0 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72  nbsp;  int xEntr
36dc0 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70  yPoint(.** &nbsp
36dd0 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62  ;    sqlite3 *db
36de0 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63  ,.** &nbsp;    c
36df0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72  onst char **pzEr
36e00 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  rMsg,.** &nbsp; 
36e10 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20     const struct 
36e20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
36e30 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20  ines *pThunk.** 
36e40 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f  &nbsp;  );.** </
36e50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
36e60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  >)^.**.** If the
36e70 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75   xEntryPoint rou
36e80 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  tine encounters 
36e90 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f  an error, it sho
36ea0 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d  uld make *pzErrM
36eb0 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  sg.** point to a
36ec0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
36ed0 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74  ror message (obt
36ee0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36ef0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a  te3_mprintf()]).
36f00 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ** and return an
36f10 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36f20 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c  ror code].  ^SQL
36f30 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 61 74  ite ensures that
36f40 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73   *pzErrMsg.** is
36f50 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c   NULL before cal
36f60 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50  ling the xEntryP
36f70 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65  oint().  ^SQLite
36f80 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
36f90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
36fa0 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66   on *pzErrMsg af
36fb0 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  ter xEntryPoint(
36fc0 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20  ) returns.  ^If 
36fd0 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  any.** xEntryPoi
36fe0 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20  nt() returns an 
36ff0 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69  error, the [sqli
37000 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
37010 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
37020 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
37030 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20  open_v2()] call 
37040 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
37050 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
37060 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  will fail..**.**
37070 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
37080 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
37090 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72  (X) with an entr
370a0 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69  y point X that i
370b0 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20  s already.** on 
370c0 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f  the list of auto
370d0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
370e0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
370f0 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20  o-op. ^No entry 
37100 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65  point.** will be
37110 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61   called more tha
37120 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  n once for each 
37130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37140 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e  ion that is open
37150 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
37160 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  so: [sqlite3_res
37170 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
37180 6e 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  n()]..*/.SQLITE_
37190 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
371a0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
371b0 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
371c0 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
371d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
371e0 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
371f0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
37200 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
37210 61 63 65 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ace disables all
37220 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
37230 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c 79  sions previously
37240 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 75  .** registered u
37250 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61 75  sing [sqlite3_au
37260 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  to_extension()].
37270 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
37280 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
37290 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
372a0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
372b0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
372c0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
372d0 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
372e0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
372f0 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
37300 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
37310 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
37320 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
37330 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
37340 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
37350 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
37360 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
37370 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
37380 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
37390 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
373a0 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
373b0 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
373c0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
373d0 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
373e0 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
373f0 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
37400 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
37410 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
37420 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
37430 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
37440 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
37450 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
37460 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
37470 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
37480 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
37490 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
374a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
374b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
374c0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
374d0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
374e0 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
374f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
37500 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
37510 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
37520 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
37530 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
37540 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
37550 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
37560 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
37570 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
37580 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
37590 6c 65 64 20 61 20 22 76 69 72 74 75 61 6c 20 74  led a "virtual t
375a0 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
375b0 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
375c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
375d0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
375e0 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
375f0 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
37600 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
37610 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
37620 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
37630 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
37640 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
37650 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
37660 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
37670 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
37680 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
37690 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
376a0 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
376b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
376c0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
376d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
376e0 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
376f0 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
37700 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
37710 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
37720 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
37730 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
37740 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
37750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37760 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
37770 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
37780 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
37790 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
377a0 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
377b0 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
377c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
377d0 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
377e0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
377f0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
37800 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
37810 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
37820 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
37830 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
37840 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
37850 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
37860 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
37870 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
37880 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
37890 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
378a0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
378b0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
378c0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
378d0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
378e0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
378f0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
37900 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
37910 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
37920 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37930 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
37940 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
37950 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
37960 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37970 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
37980 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
37990 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
379a0 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
379b0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
379c0 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
379d0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
379e0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
379f0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
37a00 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
37a10 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
37a20 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
37a30 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
37a40 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
37a50 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37a60 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
37a70 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
37a80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
37a90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
37aa0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
37ab0 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
37ac0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
37ad0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
37ae0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
37af0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
37b00 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
37b10 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
37b20 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37b30 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37b40 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
37b50 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
37b60 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
37b70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
37b80 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37b90 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
37ba0 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
37bb0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
37bc0 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
37bd0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
37be0 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
37bf0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37c00 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
37c10 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
37c20 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
37c30 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
37c40 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
37c50 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
37c60 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
37c70 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
37c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37c90 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
37ca0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37cb0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
37cc0 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
37cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37ce0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
37cf0 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
37d00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
37d10 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
37d20 4e 65 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d  New);.  /* The m
37d30 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
37d40 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
37d50 20 74 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75   the sqlite_modu
37d60 6c 65 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65  le object. Those
37d70 20 0a 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65   .  ** below are
37d80 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61   for version 2 a
37d90 6e 64 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20  nd greater. */. 
37da0 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e   int (*xSavepoin
37db0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
37dc0 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20  *pVTab, int);.  
37dd0 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28  int (*xRelease)(
37de0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37df0 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  Tab, int);.  int
37e00 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28   (*xRollbackTo)(
37e10 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37e20 54 61 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f  Tab, int);.};../
37e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
37e40 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
37e50 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
37e60 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
37e70 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
37e80 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
37e90 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
37ea0 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
37eb0 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
37ec0 73 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a  s used as part.*
37ed0 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
37ee0 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61  l table] interfa
37ef0 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ce to.** pass in
37f00 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
37f10 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
37f20 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78  eply from the [x
37f30 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65  BestIndex].** me
37f40 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75  thod of a [virtu
37f50 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
37f60 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
37f70 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
37f80 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
37f90 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
37fa0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
37fb0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
37fc0 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
37fd0 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
37fe0 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
37ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43  ..**.** ^(The aC
38000 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
38010 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
38020 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
38030 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
38040 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
38050 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
38060 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
38070 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
38080 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
38090 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29  &gt;, or &gt;=.)
380a0 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75  ^  ^(The particu
380b0 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
380c0 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
380d0 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73  nstraint[].op us
380e0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ing one of the.*
380f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  * [SQLITE_INDEX_
38100 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20  CONSTRAINT_EQ | 
38110 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
38120 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d  STRAINT_ values]
38130 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64  .)^.** ^(The ind
38140 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
38150 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
38160 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
38170 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
38180 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
38190 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
381a0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
381b0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
381c0 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
381d0 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
381e0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
381f0 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
38200 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
38210 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
38220 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
38230 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
38240 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
38250 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
38260 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
38270 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
38280 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
38290 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
382a0 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
382b0 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
382c0 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
382d0 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
382e0 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
382f0 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
38300 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
38310 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
38320 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
38330 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
38340 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
38350 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
38360 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
38370 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
38380 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
38390 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
383a0 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
383b0 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
383c0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
383d0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
383e0 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
383f0 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
38400 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
38410 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
38420 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
38430 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
38440 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
38450 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
38460 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
38470 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
38480 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
38490 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
384a0 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
384b0 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
384c0 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
384d0 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
384e0 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
384f0 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
38500 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
38510 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
38520 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
38530 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
38540 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
38550 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
38560 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
38570 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
38580 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
38590 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
385a0 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
385b0 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
385c0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
385d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
385e0 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
385f0 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
38600 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
38610 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
38620 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
38630 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
38640 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
38650 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
38660 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
38670 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
38680 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
38690 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
386a0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
386b0 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
386c0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
386d0 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
386e0 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
386f0 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
38700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
38710 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
38720 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
38730 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
38740 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
38750 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
38760 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
38770 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
38780 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
38790 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
387a0 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A bina