/ Hex Artifact Content
Login

Artifact adeb2c8019a3851a10e3872f44b34c95c6e409f2:


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 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
3e40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
3e50: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
3e60: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
3e70: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
3e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
3e90: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
3ea0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
3eb0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
3ec0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
3ed0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
3ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
3ef0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
3f00: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
3f10: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
3f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3f30: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
3f40: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
3f50: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
3f60: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3f70: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
3f80: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
3f90: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fb0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
3fc0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
3fd0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
3fe0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
3ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4000: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4010: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4020: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4040: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4050: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4060: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4070: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4080: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4090: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
40a0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
40c0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
40d0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
40e0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
40f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4100: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4110: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4120: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4130: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4140: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4160: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4170: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4180: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4190: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
41a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
41b0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
41c0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
41d0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
41e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
41f0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4200: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4210: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4220: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4240: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4250: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4260: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4270: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4290: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
42a0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
42b0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
42c0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
42d0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
42e0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
42f0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4300: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4310: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4320: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4330: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4350: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4360: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4370: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4380: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4390: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
43a0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
43b0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
43c0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
43e0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
43f0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4400: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4410: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4420: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4430: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4440: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4460: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4470: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4480: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
44a0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
44b0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
44c0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
44d0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
44f0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4500: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4510: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4520: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4530: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4540: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4550: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4570: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4580: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4590: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
45a0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
45b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
45c0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
45d0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
45e0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
45f0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4600: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4610: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4620: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4630: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4650: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4660: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4670: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4680: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4690: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
46a0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
46b0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
46c0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
46d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
46e0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
46f0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4700: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4710: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4720: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4730: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4740: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4750: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4760: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4770: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4780: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4790: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
47a0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
47b0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
47c0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
47d0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
47e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
47f0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4800: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4810: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4820: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4840: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4850: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4860: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4870: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4880: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4890: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
48a0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
48b0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
48c0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
48d0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
48e0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
48f0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4900: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4910: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4920: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4930: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4940: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4950: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4960: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4970: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4980: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4990: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
49a0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
49b0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
49c0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
49d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
49e0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
49f0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4a00: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4a10: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4a20: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4a30: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4a40: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4a50: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4a60: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4a70: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4a80: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4a90: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4aa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4ab0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4ac0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4ad0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ae0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4af0: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4b00: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4b20: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4b60: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4b70: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4b80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4b90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ba0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4bb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4bc0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4bd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4be0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4bf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c00: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c20: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c40: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4c60: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4c80: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ca0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4cc0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ce0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d00: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
4d10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d20: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
4d30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d40: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
4d50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4d60: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
4d70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4d80: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
4d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4da0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
4db0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4dc0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4de0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
4df0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e00: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
4e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e20: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
4e30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e40: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
4e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e60: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
4e70: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
4e80: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
4e90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ea0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
4eb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ec0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
4ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ee0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
4ef0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f00: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
4f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f20: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
4f30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f40: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
4f50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f60: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
4f70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f80: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
4f90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fa0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
4fb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4fc0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
4fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fe0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
4ff0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5000: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5020: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5030: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5040: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5060: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5070: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5080: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5090: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
50a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
50b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
50c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
50d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
50e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
50f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5100: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5120: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5130: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5140: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5170: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5180: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
51b0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
51c0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
51d0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
51e0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
51f0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5200: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5210: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5220: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5230: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5240: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5250: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5260: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5270: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5290: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
52a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
52b0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
52e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
52f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5300: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5340: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5350: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5370: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5390: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
53d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
53e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
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 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5420: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5440: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5460: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
54a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
54d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
54e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5500: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5510: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5550: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5560: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5590: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
55a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
55d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
55e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5610: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5620: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5640: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5650: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5660: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5670: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
56a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
56b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
56c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
56d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
56f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5700: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5710: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
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 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5740: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5750: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5760: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5790: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
57a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
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 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
57d0: 20 20 20 20 20 20 30 78 30 30 31 30 30 30 30 30        0x00100000
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 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5820: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5830: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5840: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5850: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5860: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5870: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5880: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5890: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58a0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
58b0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
58c0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
58d0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
58e0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
58f0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5900: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5910: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5920: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5930: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5940: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5950: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5960: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5980: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5990: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
59a0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
59b0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
59c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
59d0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
59e0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
59f0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5a00: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5a10: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5a20: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5a30: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5a40: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5a50: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5a60: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5a70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5a80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5a90: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5aa0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5ab0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5ac0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5ad0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5ae0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5af0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5b00: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5b10: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5b20: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5b30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b40: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5b50: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5b60: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5b70: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5b80: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5b90: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ba0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5bd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5bf0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5c00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5c40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5c70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5c90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5cb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5cd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5ce0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5cf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5d00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5d20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5d30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5d50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5d70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5d90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5db0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5dc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5de0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5df0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5e10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5e20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5e30: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5e40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5e50: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5e60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5e70: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5e80: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5e90: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5ea0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5eb0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5ec0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5ed0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5ee0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5ef0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5f00: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5f10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
5f20: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f40: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
5f70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
5f80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5f90: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
5fa0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
5fb0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
5fc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
5fd0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
5fe0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
5ff0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6000: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6010: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6020: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6030: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6040: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6050: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6060: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6070: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6080: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6090: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
60a0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
60b0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
60c0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
60d0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
60e0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
60f0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6100: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6110: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6120: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6130: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6140: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6150: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6170: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6180: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6190: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
61a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
61b0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
61c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
61d0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
61e0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
61f0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
6200: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
6210: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6220: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6230: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6240: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6250: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6260: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6270: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6280: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6290: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
62a0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
62b0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
62c0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
62d0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
62e0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
62f0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
6300: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
6310: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6320: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6330: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6340: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6350: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6360: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
6370: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
6380: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
6390: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
63a0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
63b0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
63c0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
63d0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
63e0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
63f0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
6400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
6410: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6420: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6430: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6440: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6450: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6460: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
6470: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
6480: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
6490: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
64a0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
64b0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
64c0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
64d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
64e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
64f0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
6500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6510: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6520: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6530: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6540: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6550: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6560: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
6570: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
6580: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
6590: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
65a0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
65b0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
65c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
65d0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
65e0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
65f0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
6600: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
6610: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6620: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6630: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6640: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6650: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6660: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6670: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6680: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6690: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
66a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
66b0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
66c0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
66d0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
66e0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
66f0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
6700: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6710: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6720: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6730: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6740: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6750: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6760: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6770: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6780: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
67a0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
67b0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
67c0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
67d0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
67e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
67f0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
6800: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
6810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6820: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6830: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6840: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6860: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
6870: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6880: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
6890: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
68a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
68b0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
68c0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
68d0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
68e0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
68f0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
6900: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
6910: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6920: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65  *.** If the xOpe
6930: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  n method sets th
6940: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6950: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
6960: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
6970: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
6980: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
6990: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
69a0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
69b0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
69c0: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65  he xOpen reporte
69d0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
69e0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
69f0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
6a00: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
6a10: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
6a20: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f  d xOpen.** is fo
6a30: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73  r the xOpen to s
6a40: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
6a50: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6a60: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ment to NULL..**
6a70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
6a80: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
6a90: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
6aa0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ab0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
6ac0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
6ad0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
6ae0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
6af0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
6b00: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
6b10: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6b20: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
6b30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6b40: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
6b50: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
6b60: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
6b70: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
6b80: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
6b90: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
6ba0: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
6bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
6bc0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
6bd0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6be0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
6bf0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
6c00: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
6c10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
6c30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6c40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
6c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6c60: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
6c70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6c90: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
6ca0: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
6cb0: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
6cc0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
6cd0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
6ce0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
6cf0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
6d00: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
6d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6d20: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
6d30: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
6d40: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
6d50: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
6d60: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
6d70: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
6d80: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
6d90: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
6da0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
6db0: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
6dc0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
6dd0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
6de0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
6df0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
6e00: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
6e10: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
6e20: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
6e30: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
6e40: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
6e50: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
6e60: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
6e70: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
6e80: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
6e90: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
6ea0: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
6eb0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
6ec0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
6ed0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
6ee0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
6ef0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
6f00: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
6f10: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
6f20: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
6f30: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
6f40: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
6f50: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
6f60: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
6f70: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
6f80: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
6f90: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
6fa0: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
6fb0: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
6fc0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
6fd0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
6fe0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
6ff0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7000: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7010: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7020: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7030: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7040: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7050: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7060: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7070: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7080: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
7090: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
70a0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
70b0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
70c0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
70d0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
70e0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
70f0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7100: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7110: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7120: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7130: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7140: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7160: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7170: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7180: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7190: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
71a0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
71b0: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
71c0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
71d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
71e0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
71f0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7200: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7210: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7220: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7230: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7240: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7250: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7260: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
7270: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
7280: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
7290: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
72a0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
72b0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
72c0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
72d0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
72e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
72f0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
7300: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7310: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
7320: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7330: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
7340: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7350: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
7360: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7370: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
7380: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7390: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
73a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
73b0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
73c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
73d0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
73e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
73f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
7400: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
7420: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7430: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7440: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
7450: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7460: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
7470: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
7480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
7490: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
74a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
74b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
74c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
74d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
74e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
74f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
7500: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
7510: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
7520: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
7530: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
7540: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
7550: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
7560: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
7570: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
7580: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7590: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
75a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
75b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
75c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
75d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
75e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
75f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
7600: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
7610: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
7620: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
7630: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7640: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
7650: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
7660: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
7670: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
7680: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
7690: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
76a0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
76b0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
76c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
76d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
76e0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
76f0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
7700: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
7710: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
7720: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
7730: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
7740: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7750: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
7760: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
7770: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
7780: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
7790: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
77a0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
77b0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
77c0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
77d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
77e0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
77f0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
7800: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7810: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
7820: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
7830: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
7840: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
7850: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
7860: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
7870: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
7880: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
7890: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
78a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
78b0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
78c0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
78d0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
78e0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
78f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7900: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
7910: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
7920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7930: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
7940: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
7950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
7960: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
7970: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
7980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7990: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
79a0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
79b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
79c0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
79d0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
79e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
79f0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
7a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
7a10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7a20: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
7a30: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
7a40: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7a50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
7a60: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7a70: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
7a80: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
7a90: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7aa0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
7ab0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
7ac0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
7ad0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
7ae0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
7af0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
7b00: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
7b10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7b20: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
7b30: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
7b40: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
7b50: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
7b60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
7b70: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
7b90: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
7ba0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
7bb0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
7bc0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  2 */.  /* Additi
7bd0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
7be0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
7bf0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
7c00: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7c10: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
7c20: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
7c30: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
7c40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7c50: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7c60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7c70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7c80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7c90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7ca0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7cb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7cc0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7cd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7ce0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7cf0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
7d00: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
7d10: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
7d20: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
7d30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7d40: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7d50: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7d60: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7d70: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7d80: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7d90: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7da0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7db0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7dc0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7dd0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
7de0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
7df0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
7e00: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
7e10: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
7e20: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
7e30: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7e40: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7e50: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7e60: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7e70: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7e80: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
7e90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7ea0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
7eb0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
7ec0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
7ed0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
7ee0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
7ef0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
7f00: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
7f10: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
7f20: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
7f30: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
7f40: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
7f50: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
7f60: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
7f70: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
7f80: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
7f90: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
7fa0: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
7fb0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
7fc0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
7fd0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
7fe0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
7ff0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8000: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8010: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  r..**.** The [SQ
8020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8030: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8040: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8050: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8060: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8070: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8080: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8090: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
80a0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
80b0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
80c0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
80d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
80e0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
80f0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8100: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8110: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8120: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
8130: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
8140: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8150: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8160: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8170: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8180: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8190: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
81a0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
81b0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
81c0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
81d0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
81e0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
81f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8200: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
8210: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
8220: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
8230: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
8240: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
8250: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
8260: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
8270: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
8280: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
8290: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
82a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
82b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
82c0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
82d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
82e0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  ^(The [SQLITE_FC
82f0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8300: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
8310: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
8320: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e   by.** SQLite an
8330: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46  d sent to all VF
8340: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  Ses in place of 
8350: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53  a call to the xS
8360: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68  ync method.** wh
8370: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
8380: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b  connection has [
8390: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
83a0: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29  us] set to OFF.)
83b0: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61  ^.** Some specia
83c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64  lized VFSes need
83d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20   this signal in 
83e0: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65  order to operate
83f0: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68   correctly.** wh
8400: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  en [PRAGMA synch
8410: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
8420: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
8430: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73   is set, but mos
8440: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e  t .** VFSes do n
8450: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
8460: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73  nal and should s
8470: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
8480: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41  his opcode..** A
8490: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
84a0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
84b0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
84c0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a  l()] with this.*
84d0: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  * opcode as doin
84e0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
84f0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
8500: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
8510: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20  d VFSes.** that 
8520: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
8530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8540: 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f 4e 4c  TE_FCNTL_READONL
8550: 59 5f 53 48 4d 5d 20 6d 61 79 20 62 65 20 67 65  Y_SHM] may be ge
8560: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
8570: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 69 66 0a  ly by SQLite if.
8580: 2a 2a 20 74 68 65 20 22 72 65 61 64 6f 6e 6c 79  ** the "readonly
8590: 5f 73 68 6d 3d 31 22 20 55 52 49 20 6f 70 74 69  _shm=1" URI opti
85a0: 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20  on is specified 
85b0: 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
85c0: 65 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20  e is opened..** 
85d0: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
85e0: 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20 74 68  ent passed to th
85f0: 65 20 56 46 53 20 78 46 69 6c 65 43 6f 6e 74 72  e VFS xFileContr
8600: 6f 6c 20 6d 65 74 68 6f 64 73 20 69 73 20 61 20  ol methods is a 
8610: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20  pointer.** to a 
8620: 76 61 72 69 61 62 6c 65 20 6f 66 20 74 79 70 65  variable of type
8630: 20 22 69 6e 74 22 20 63 6f 6e 74 61 69 6e 69 6e   "int" containin
8640: 67 20 74 68 65 20 76 61 6c 75 65 20 31 20 6f 72  g the value 1 or
8650: 20 30 2e 20 49 66 20 74 68 65 20 76 61 72 69 61   0. If the varia
8660: 62 6c 65 0a 2a 2a 20 63 6f 6e 74 61 69 6e 73 20  ble.** contains 
8670: 74 68 65 20 76 61 6c 75 65 20 31 2c 20 74 68 65  the value 1, the
8680: 6e 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73  n this indicates
8690: 20 74 6f 20 74 68 65 20 56 46 53 20 74 68 61 74   to the VFS that
86a0: 20 61 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 20   a read-only.** 
86b0: 6d 61 70 70 69 6e 67 20 6f 66 20 74 68 65 20 73  mapping of the s
86c0: 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 72 65 67  hared-memory reg
86d0: 69 6f 6e 20 69 73 20 61 63 63 65 70 74 61 62 6c  ion is acceptabl
86e0: 65 2e 20 49 66 20 69 74 20 69 73 20 73 65 74 20  e. If it is set 
86f0: 74 6f 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  to 0, then.** th
8700: 69 73 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  is indicates tha
8710: 74 20 61 20 72 65 61 64 2d 77 72 69 74 65 20 6d  t a read-write m
8720: 61 70 70 69 6e 67 20 69 73 20 72 65 71 75 69 72  apping is requir
8730: 65 64 20 28 61 73 20 6e 6f 72 6d 61 6c 29 2e 20  ed (as normal). 
8740: 49 66 0a 2a 2a 20 61 20 72 65 61 64 2d 6f 6e 6c  If.** a read-onl
8750: 79 20 6d 61 70 70 69 6e 67 20 69 73 20 72 65 74  y mapping is ret
8760: 75 72 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  urned, then the 
8770: 56 46 53 20 6d 61 79 20 61 6c 73 6f 20 72 65 74  VFS may also ret
8780: 75 72 6e 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a  urn read-only.**
8790: 20 6d 61 70 70 69 6e 67 73 20 66 6f 72 20 61 6e   mappings for an
87a0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 71  y subsequent req
87b0: 75 65 73 74 73 20 76 69 61 20 74 68 65 20 73 61  uests via the sa
87c0: 6d 65 20 66 69 6c 65 2d 64 65 73 63 72 69 70 74  me file-descript
87d0: 6f 72 20 2d 0a 2a 2a 20 72 65 67 61 72 64 6c 65  or -.** regardle
87e0: 73 73 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20  ss of the value 
87f0: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
8800: 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a  nfigured using.*
8810: 2a 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  * SQLITE_FCNTL_R
8820: 45 41 44 4f 4e 4c 59 5f 53 48 4d 2e 0a 2a 2a 0a  EADONLY_SHM..**.
8830: 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20  ** In practice, 
8840: 69 66 20 22 72 65 61 64 6f 6e 6c 79 5f 73 68 6d  if "readonly_shm
8850: 3d 31 22 20 69 73 20 73 70 65 63 69 66 69 65 64  =1" is specified
8860: 20 61 6e 64 20 74 68 65 20 66 69 72 73 74 20 61   and the first a
8870: 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 6d 61 70  ttempt to.** map
8880: 20 61 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79   a shared-memory
8890: 20 72 65 67 69 6f 6e 20 66 61 69 6c 73 2c 20 74   region fails, t
88a0: 68 65 6e 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  hen this file-co
88b0: 6e 74 72 6f 6c 20 69 73 20 69 6e 76 6f 6b 65 64  ntrol is invoked
88c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 61 72 67   with.** the arg
88d0: 75 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 20 73  ument variable s
88e0: 65 74 20 74 6f 20 31 20 61 6e 64 20 61 20 73 65  et to 1 and a se
88f0: 63 6f 6e 64 20 61 74 74 65 6d 70 74 20 74 6f 20  cond attempt to 
8900: 6d 61 70 20 74 68 65 20 73 68 61 72 65 64 2d 6d  map the shared-m
8910: 65 6d 6f 72 79 0a 2a 2a 20 72 65 67 69 6f 6e 20  emory.** region 
8920: 69 73 20 6d 61 64 65 2e 20 49 66 20 74 68 69 73  is made. If this
8930: 20 6d 61 70 70 69 6e 67 20 73 75 63 63 65 65 64   mapping succeed
8940: 73 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 6e  s, then the conn
8950: 65 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73  ection continues
8960: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 72 65 61  .** with the rea
8970: 64 2d 6f 6e 6c 79 20 6d 61 70 70 69 6e 67 2e 20  d-only mapping. 
8980: 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 69 74  Otherwise, if it
8990: 20 66 61 69 6c 73 2c 20 53 51 4c 49 54 45 5f 43   fails, SQLITE_C
89a0: 41 4e 54 4f 50 45 4e 20 69 73 0a 2a 2a 20 72 65  ANTOPEN is.** re
89b0: 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
89c0: 6c 6c 65 72 2e 20 57 68 65 74 68 65 72 20 6f 72  ller. Whether or
89d0: 20 6e 6f 74 20 74 68 65 20 73 65 63 6f 6e 64 20   not the second 
89e0: 28 72 65 61 64 2d 6f 6e 6c 79 29 20 6d 61 70 70  (read-only) mapp
89f0: 69 6e 67 0a 2a 2a 20 61 74 74 65 6d 70 74 20 73  ing.** attempt s
8a00: 75 63 63 65 65 64 73 2c 20 74 68 65 20 66 69 6c  ucceeds, the fil
8a10: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 69 6e 76  e-control is inv
8a20: 6f 6b 65 64 20 61 67 61 69 6e 20 77 69 74 68 20  oked again with 
8a30: 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
8a40: 76 61 72 69 61 62 6c 65 20 73 65 74 20 74 6f 20  variable set to 
8a50: 30 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  0..*/.#define SQ
8a60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
8a70: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64  TATE        1.#d
8a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
8a90: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
8aa0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
8ab0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
8ac0: 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64  XYFILE      3.#d
8ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
8ae0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
8af0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
8b00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8b10: 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64  HINT        5.#d
8b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
8b30: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
8b40: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
8b50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8b60: 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64  POINTER     7.#d
8b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
8b80: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
8b90: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
8ba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f  LITE_FCNTL_READO
8bb0: 4e 4c 59 5f 53 48 4d 20 20 20 20 20 39 0a 0a 0a  NLY_SHM     9...
8bc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8bd0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
8be0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
8bf0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
8c00: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
8c10: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
8c20: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
8c30: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
8c40: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
8c50: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
8c60: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
8c70: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
8c80: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
8c90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
8ca0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
8cb0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
8cc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
8cd0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
8ce0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
8cf0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
8d00: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
8d10: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
8d20: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8d30: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
8d40: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
8d50: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
8d60: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
8d70: 57 4f 52 44 53 3a 20 56 46 53 20 56 46 53 65 73  WORDS: VFS VFSes
8d80: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
8d90: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
8da0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
8db0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
8dc0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
8dd0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
8de0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
8df0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
8e00: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
8e10: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
8e20: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
8e30: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
8e40: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
8e50: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
8e60: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
8e70: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
8e80: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
8e90: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
8ea0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
8eb0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
8ec0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
8ed0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
8ee0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
8ef0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
8f00: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
8f10: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
8f20: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
8f30: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
8f40: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
8f50: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
8f60: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
8f70: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
8f80: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
8f90: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
8fa0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
8fb0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
8fc0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
8fd0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
8fe0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
8ff0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
9000: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
9010: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
9020: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
9030: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
9040: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
9050: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
9060: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
9070: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
9080: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
9090: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
90a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
90b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
90c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
90d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
90e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
90f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
9100: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
9110: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
9120: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
9130: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
9140: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
9150: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
9160: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
9170: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
9180: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
9190: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
91a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
91b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
91c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
91d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
91e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
91f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
9200: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
9210: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
9220: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
9230: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
9240: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
9250: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
9260: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
9270: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
9280: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
9290: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
92a0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
92b0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
92c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
92d0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
92e0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
92f0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
9300: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
9310: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
9320: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
9330: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
9340: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
9350: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
9360: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
9370: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
9380: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
9390: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
93a0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
93b0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
93c0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
93d0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
93e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
93f0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
9400: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
9410: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
9420: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
9430: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
9440: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
9450: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
9460: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
9470: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
9480: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20  more than.** 10 
9490: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
94a0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
94b0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
94c0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
94d0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
94e0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
94f0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
9500: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
9510: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
9520: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
9530: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
9540: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
9550: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
9560: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
9570: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
9580: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
9590: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
95a0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
95b0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
95c0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
95d0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
95e0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
95f0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
9600: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
9610: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
9620: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
9630: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
9640: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
9650: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
9660: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
9670: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
9680: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
9690: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
96a0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
96b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
96c0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
96d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
96e0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
96f0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
9700: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
9710: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
9720: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
9730: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
9740: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
9750: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
9760: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
9770: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
9780: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
9790: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
97a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
97b0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
97c0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
97d0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
97e0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
97f0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
9800: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
9810: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
9820: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
9830: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
9840: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
9850: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
9860: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
9870: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
9880: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
9890: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
98a0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
98b0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
98c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
98d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
98e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
98f0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
9900: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9910: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
9920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9930: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
9940: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
9950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
9960: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
9970: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
9980: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
9990: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
99a0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
99b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
99c0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
99d0: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
99e0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
99f0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
9a00: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
9a10: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
9a20: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
9a30: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
9a40: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
9a50: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
9a60: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
9a70: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
9a80: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
9a90: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
9aa0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
9ab0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
9ac0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
9ad0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
9ae0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
9af0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
9b00: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
9b10: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
9b20: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
9b30: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
9b40: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
9b50: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
9b60: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
9b70: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
9b80: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
9b90: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
9ba0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
9bb0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
9bc0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
9bd0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
9be0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
9bf0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
9c00: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
9c10: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
9c20: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
9c30: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
9c40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
9c50: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
9c60: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
9c70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
9c80: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
9c90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
9ca0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9cb0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
9cc0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
9cd0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
9ce0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
9cf0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
9d00: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9d10: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
9d20: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
9d30: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
9d40: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
9d50: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
9d60: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
9d70: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
9d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
9d90: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
9da0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
9db0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
9dc0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
9dd0: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
9de0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
9df0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
9e00: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
9e10: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
9e20: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
9e30: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
9e40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
9e50: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
9e60: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
9e70: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
9e80: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
9e90: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
9ea0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
9eb0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
9ec0: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
9ed0: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
9ee0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
9ef0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
9f00: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
9f10: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
9f20: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
9f30: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
9f40: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
9f50: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
9f60: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
9f70: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
9f80: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
9f90: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
9fa0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
9fb0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
9fc0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
9fd0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
9fe0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
9ff0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
a000: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
a010: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
a020: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
a030: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
a040: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
a050: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
a060: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
a070: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
a080: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
a090: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
a0a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
a0b0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
a0c0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
a0d0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
a0e0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
a0f0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
a100: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
a110: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
a120: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
a130: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
a140: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
a150: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
a160: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
a170: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
a180: 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c  l..**.** ^The fl
a190: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
a1a0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
a1b0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
a1c0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
a1d0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
a1e0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
a1f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
a200: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
a210: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
a220: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
a230: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
a240: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
a250: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
a260: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
a270: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
a280: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
a290: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
a2a0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
a2b0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
a2c0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
a2d0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
a2e0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
a2f0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
a300: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
a310: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
a320: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
a330: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
a340: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
a350: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
a360: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
a370: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
a380: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
a390: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
a3a0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
a3b0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
a3c0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
a3d0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
a3e0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
a3f0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
a400: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
a410: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
a420: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
a430: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
a440: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
a450: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
a460: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
a470: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
a480: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
a490: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
a4a0: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
a4b0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
a4c0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
a4d0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
a4e0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
a4f0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
a500: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
a510: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
a520: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
a530: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
a540: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
a550: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
a560: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
a570: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
a580: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
a590: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
a5a0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
a5b0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
a5c0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
a5d0: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
a5e0: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
a5f0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
a600: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
a610: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
a620: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
a630: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
a640: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a650: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
a660: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
a670: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
a680: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
a690: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
a6a0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
a6b0: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
a6c0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
a6d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a6e0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
a6f0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
a700: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
a710: 70 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30  pled by 86400000
a720: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
a730: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
a740: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
a750: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
a760: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
a770: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a780: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
a790: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
a7a0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
a7b0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
a7c0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
a7d0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
a7e0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
a7f0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
a800: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
a810: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
a820: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
a830: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
a840: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
a850: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
a860: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
a870: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
a880: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
a890: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
a8a0: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
a8b0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
a8c0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
a8d0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
a8e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
a8f0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
a900: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
a910: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
a920: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
a930: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
a940: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
a950: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
a960: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
a970: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
a980: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
a990: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
a9a0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
a9b0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
a9c0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
a9d0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
a9e0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
a9f0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
aa00: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
aa10: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
aa20: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
aa30: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
aa40: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
aa50: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
aa60: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
aa70: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
aa80: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
aa90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
aaa0: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
aab0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
aac0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
aad0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
aae0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
aaf0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
ab00: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
ab10: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
ab20: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
ab30: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
ab40: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
ab50: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
ab60: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
ab70: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
ab80: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
ab90: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
aba0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
abb0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
abc0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
abd0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
abe0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
abf0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
ac00: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
ac10: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
ac20: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
ac30: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
ac40: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
ac50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
ac60: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
ac70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
ac80: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
ac90: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
aca0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
acb0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
acc0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
acd0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
ace0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
acf0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
ad00: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
ad10: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
ad20: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
ad30: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
ad40: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
ad50: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
ad60: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
ad70: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
ad80: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
ad90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ada0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
adb0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
adc0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
add0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
ade0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
adf0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
ae00: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ae10: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
ae20: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
ae30: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
ae40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ae50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
ae60: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
ae70: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
ae80: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
ae90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
aea0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
aeb0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
aec0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
aed0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
aee0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
aef0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
af00: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
af10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
af20: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
af30: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
af40: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
af50: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
af60: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
af70: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
af80: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
af90: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
afa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
afb0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
afc0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
afd0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
afe0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
aff0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
b000: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
b010: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b020: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
b030: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
b040: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
b050: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
b060: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
b070: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
b080: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
b090: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
b0a0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b0b0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
b0c0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
b0d0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
b0e0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
b0f0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
b100: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
b110: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
b120: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
b130: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
b140: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b150: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b160: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
b170: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
b180: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
b190: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
b1a0: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
b1b0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
b1c0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
b1d0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
b1e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b1f0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
b200: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
b210: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
b220: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
b230: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b240: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b250: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
b260: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
b270: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
b280: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
b290: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
b2a0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
b2b0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
b2c0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
b2d0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
b2e0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
b2f0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
b300: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
b310: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
b320: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
b330: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
b340: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
b350: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
b360: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
b370: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
b380: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
b390: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
b3a0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
b3b0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
b3c0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
b3d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
b3e0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
b3f0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
b400: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
b410: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
b420: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
b430: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
b440: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
b450: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
b460: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
b470: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
b480: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
b490: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
b4a0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
b4b0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
b4c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b4d0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
b4e0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
b4f0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
b500: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
b510: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
b520: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
b530: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
b540: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
b550: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
b560: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
b570: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
b580: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
b590: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b5a0: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
b5b0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
b5c0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
b5d0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
b5e0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
b5f0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
b600: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
b610: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
b620: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
b630: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
b640: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
b650: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
b660: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
b670: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
b680: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
b690: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
b6a0: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
b6b0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
b6c0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
b6d0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
b6e0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
b6f0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
b700: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
b710: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
b720: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
b730: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
b740: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
b750: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
b760: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
b770: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b780: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
b790: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
b7a0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
b7b0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
b7c0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
b7d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
b7e0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
b7f0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
b800: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
b810: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
b820: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
b830: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
b840: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
b850: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
b860: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
b870: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
b880: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
b890: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b8a0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
b8b0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
b8c0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
b8d0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
b8e0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
b8f0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b900: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
b910: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
b920: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
b930: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
b940: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
b950: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
b960: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
b970: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
b980: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
b990: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
b9a0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
b9b0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
b9c0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
b9d0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
b9e0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
b9f0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
ba00: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
ba10: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
ba20: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
ba30: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
ba40: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
ba50: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
ba60: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ba70: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
ba80: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
ba90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
baa0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
bab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bac0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
bad0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
bae0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
baf0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bb00: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
bb10: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
bb20: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
bb30: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
bb40: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
bb50: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
bb60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
bb70: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
bb80: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
bb90: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
bba0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
bbb0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
bbc0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
bbd0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
bbe0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
bbf0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
bc00: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
bc10: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
bc20: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
bc30: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
bc40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
bc50: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
bc60: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
bc70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
bc80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
bc90: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
bca0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
bcb0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
bcc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bcd0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
bce0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
bcf0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
bd00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
bd10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd20: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
bd30: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
bd40: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
bd50: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
bd60: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
bd70: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
bd80: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
bd90: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
bda0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
bdb0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
bdc0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
bdd0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
bde0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
bdf0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
be00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
be10: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
be20: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
be30: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
be40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
be50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
be60: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
be70: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
be80: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
be90: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
bea0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
beb0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
bec0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
bed0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
bee0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
bef0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
bf00: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
bf10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bf20: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
bf30: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
bf40: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
bf50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
bf60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
bf70: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
bf80: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
bf90: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
bfa0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
bfb0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
bfc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bfd0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
bfe0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
bff0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
c000: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
c010: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
c020: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
c030: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
c040: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
c050: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
c060: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c070: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
c080: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
c090: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
c0a0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
c0b0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
c0c0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
c0d0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
c0e0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
c0f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
c100: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
c110: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
c120: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
c130: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
c140: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c150: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
c160: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
c170: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
c180: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
c190: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
c1a0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
c1b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c1c0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
c1d0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
c1e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c1f0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
c200: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
c210: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
c220: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
c230: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
c240: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
c250: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
c260: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c270: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
c280: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
c290: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
c2a0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
c2b0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
c2c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
c2d0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
c2e0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
c2f0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
c300: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
c310: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
c320: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
c330: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
c340: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
c350: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
c360: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
c370: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
c380: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
c390: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
c3a0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
c3b0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
c3c0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
c3d0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
c3e0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
c3f0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
c400: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
c410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
c420: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
c430: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
c440: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
c450: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c460: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
c470: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
c480: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
c490: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
c4a0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
c4b0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
c4c0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
c4d0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
c4e0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
c4f0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
c500: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
c510: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
c520: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
c530: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
c540: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
c550: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
c560: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c570: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
c580: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
c590: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
c5a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c5b0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
c5c0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
c5d0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
c5e0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
c5f0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
c600: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
c610: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
c620: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
c630: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
c640: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
c650: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
c660: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
c670: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
c680: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
c690: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
c6a0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
c6b0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
c6c0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
c6d0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
c6e0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
c6f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
c700: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
c710: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
c720: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
c730: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
c740: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
c750: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
c760: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
c770: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
c780: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
c790: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
c7a0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
c7b0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
c7c0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
c7d0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
c7e0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
c7f0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
c800: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
c810: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
c820: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
c830: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
c840: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
c850: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
c860: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
c870: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
c880: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
c890: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
c8a0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
c8b0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
c8c0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
c8d0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
c8e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
c8f0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
c900: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
c910: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
c920: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c930: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
c940: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c950: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
c960: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
c970: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
c980: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
c990: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
c9a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
c9b0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
c9c0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
c9d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
c9e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
c9f0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
ca00: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
ca10: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
ca20: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
ca30: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
ca40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ca50: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
ca60: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
ca70: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
ca80: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ca90: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
caa0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
cab0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
cac0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
cad0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
cae0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
caf0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
cb00: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
cb10: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
cb20: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
cb30: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
cb40: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
cb50: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
cb60: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
cb70: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
cb80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
cb90: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
cba0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
cbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
cbc0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
cbd0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
cbe0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
cbf0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
cc00: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
cc10: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
cc20: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
cc30: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
cc40: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
cc50: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
cc60: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
cc70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
cc80: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
cc90: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
cca0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
ccb0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
ccc0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
ccd0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
cce0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
ccf0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
cd00: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
cd10: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
cd20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
cd30: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
cd40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
cd50: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
cd60: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
cd70: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
cd80: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
cd90: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
cda0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
cdb0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
cdc0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
cdd0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
cde0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
cdf0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
ce00: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
ce10: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
ce20: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
ce30: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
ce40: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
ce50: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
ce60: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
ce70: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
ce80: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
ce90: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
cea0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
ceb0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
cec0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
ced0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
cee0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
cef0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
cf00: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
cf10: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
cf20: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
cf30: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
cf40: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
cf50: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
cf60: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
cf70: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
cf80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
cf90: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
cfa0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
cfb0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
cfc0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cfd0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
cfe0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
cff0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
d000: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
d010: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
d020: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
d030: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
d040: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
d050: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
d060: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
d070: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
d080: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
d090: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
d0a0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
d0b0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
d0c0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
d0d0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d0e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d0f0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
d100: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
d110: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
d120: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d130: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
d140: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
d150: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
d160: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
d170: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
d180: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
d190: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
d1a0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
d1b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
d1c0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
d1d0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
d1e0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d1f0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
d200: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
d210: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
d220: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d230: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d240: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
d250: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
d260: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
d270: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
d280: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
d290: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
d2a0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
d2b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
d2c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
d2d0: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
d2e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d2f0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
d300: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
d310: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d320: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
d330: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
d340: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
d350: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
d360: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
d370: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
d380: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
d390: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
d3a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
d3b0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
d3c0: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
d3d0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
d3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d3f0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
d400: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d410: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
d420: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d430: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
d440: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
d450: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
d460: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
d470: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
d480: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
d490: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
d4a0: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
d4b0: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
d4c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d4d0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
d4e0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
d4f0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
d500: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
d510: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
d520: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
d530: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
d540: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d550: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
d560: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
d570: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
d580: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
d590: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
d5a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
d5b0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
d5c0: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
d5d0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
d5e0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
d5f0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
d600: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
d610: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
d620: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
d630: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
d640: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
d650: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d660: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
d670: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
d680: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
d690: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
d6a0: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
d6b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
d6c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
d6d0: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
d6e0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
d6f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d700: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
d710: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
d720: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
d730: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
d740: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d750: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
d760: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
d770: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
d780: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
d790: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
d7a0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
d7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d7c0: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
d7d0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
d7e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
d7f0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
d800: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
d810: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
d820: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
d830: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
d840: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
d850: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
d860: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
d870: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
d880: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
d890: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
d8a0: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
d8b0: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
d8c0: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
d8d0: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
d8e0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
d8f0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
d900: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
d910: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
d920: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
d930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
d940: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
d950: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
d960: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
d970: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
d980: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
d990: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
d9a0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
d9b0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
d9c0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
d9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
d9e0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
d9f0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
da00: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
da10: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
da20: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
da30: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
da40: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
da50: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
da60: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61  ** The xMalloc a
da70: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
da80: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
da90: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20  the.** malloc() 
daa0: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
dab0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
dac0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
dad0: 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f  ..** The xReallo
dae0: 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f  c method must wo
daf0: 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28  rk like realloc(
db00: 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  ) from the stand
db10: 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a  ard C library.**
db20: 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74   with the except
db30: 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20  ion that if the 
db40: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
db50: 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a  to xRealloc is z
db60: 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ero,.** xRealloc
db70: 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70   must be a no-op
db80: 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70   - it must not p
db90: 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63  erform any alloc
dba0: 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c  ation or.** deal
dbb0: 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69  location.  ^SQLi
dbc0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
dbd0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
dbe0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
dbf0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
dc00: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
dc10: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
dc20: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
dc30: 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73   And so in cases
dc40: 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20   where xRoundup 
dc50: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
dc60: 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
dc70: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61  ,.** xRealloc ca
dc80: 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c  n perform exactl
dc90: 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72  y as the standar
dca0: 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f  d library reallo
dcb0: 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c  c() and.** still
dcc0: 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63   be in complianc
dcd0: 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63  e with this spec
dce0: 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ification..**.**
dcf0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
dd00: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
dd10: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
dd20: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
dd30: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
dd40: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
dd50: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
dd60: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
dd70: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
dd80: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
dd90: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
dda0: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
ddb0: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
ddc0: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
ddd0: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
dde0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
ddf0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
de00: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
de10: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
de20: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
de30: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
de40: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
de50: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
de60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
de70: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
de80: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
de90: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
dea0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
deb0: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
dec0: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
ded0: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
dee0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
def0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
df00: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
df10: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
df20: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
df30: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
df40: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
df50: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
df60: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
df70: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
df80: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
df90: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
dfa0: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
dfb0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
dfc0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
dfd0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
dfe0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
dff0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
e000: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
e010: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
e020: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
e030: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
e040: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
e050: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
e060: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
e070: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
e080: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
e090: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
e0a0: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
e0b0: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
e0c0: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
e0d0: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
e0e0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
e0f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e100: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
e110: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
e120: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
e130: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
e140: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
e150: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
e160: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
e170: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
e180: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
e190: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
e1a0: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
e1b0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
e1c0: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
e1d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e1e0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
e1f0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
e200: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
e210: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
e220: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
e230: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
e240: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
e250: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
e260: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
e270: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e280: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
e290: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
e2a0: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
e2b0: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
e2c0: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
e2d0: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
e2e0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
e2f0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
e300: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
e310: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
e320: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
e330: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
e340: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
e350: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
e360: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
e370: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
e380: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
e390: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
e3a0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
e3b0: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
e3c0: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
e3d0: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
e3e0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
e3f0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
e400: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e410: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e420: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
e430: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
e440: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e450: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
e460: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
e470: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
e480: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
e490: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
e4a0: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
e4b0: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
e4c0: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
e4d0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
e4e0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
e4f0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
e500: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
e510: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
e520: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
e530: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
e540: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
e550: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
e560: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
e570: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
e580: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
e590: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
e5a0: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
e5b0: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
e5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
e5d0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
e5e0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
e5f0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
e600: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
e610: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
e620: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e630: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
e640: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e650: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
e660: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
e670: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
e680: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
e690: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
e6a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
e6b0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
e6c0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
e6d0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
e6e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e6f0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
e700: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
e710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e720: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
e730: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
e740: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
e750: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e760: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
e770: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
e780: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
e790: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
e7a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e7b0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
e7c0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
e7d0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
e7e0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
e7f0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
e800: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
e810: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
e820: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
e830: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
e840: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
e850: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
e860: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
e870: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
e880: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
e890: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
e8a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e8b0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
e8c0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
e8d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e8e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
e8f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e900: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e910: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e920: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
e930: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
e940: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
e950: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
e960: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e970: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
e980: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
e990: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
e9a0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
e9b0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
e9c0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
e9d0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
e9e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e9f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ea00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ea10: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
ea20: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
ea30: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
ea40: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
ea50: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
ea60: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
ea70: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
ea80: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
ea90: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
eaa0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
eab0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
eac0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
ead0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
eae0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
eaf0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
eb00: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
eb10: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
eb20: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eb30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
eb40: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
eb50: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
eb60: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
eb70: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
eb80: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
eba0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
ebb0: 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
ebc0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
ebd0: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
ebe0: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
ebf0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
ec00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
ec10: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
ec20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
ec30: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
ec40: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
ec50: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
ec60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ec70: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
ec80: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
ec90: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
eca0: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
ecb0: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
ecc0: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
ecd0: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
ece0: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
ecf0: 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
ed00: 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
ed10: 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
ed20: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
ed30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ed40: 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
ed50: 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
ed60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
ed70: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
ed80: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
ed90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
eda0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
edb0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
edc0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
edd0: 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
ede0: 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
edf0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
ee00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ee10: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
ee20: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
ee30: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
ee40: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
ee50: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
ee60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ee70: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
ee80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ee90: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
eea0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
eeb0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
eec0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
eed0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
eee0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
eef0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
ef00: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
ef10: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
ef20: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
ef30: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
ef40: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
ef50: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
ef60: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
ef70: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
ef80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ef90: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
efa0: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
efb0: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
efc0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
efd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
efe0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
eff0: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
f000: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
f010: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
f020: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
f030: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f040: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
f050: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
f060: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
f070: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
f080: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
f090: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
f0a0: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
f0b0: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
f0c0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
f0d0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
f0e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
f0f0: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
f100: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f110: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
f120: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
f130: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
f140: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
f150: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
f160: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
f170: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
f180: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
f190: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
f1a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f1b0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
f1c0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
f1d0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
f1e0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
f1f0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
f200: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f210: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
f220: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f230: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
f240: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f250: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f260: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f270: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f280: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f290: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f2a0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f2b0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
f2c0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
f2d0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
f2e0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
f2f0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
f300: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
f310: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
f320: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f330: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
f340: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
f350: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
f360: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
f370: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
f380: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
f390: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f3a0: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
f3b0: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
f3c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
f3d0: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
f3e0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f3f0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f400: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
f410: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f420: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f430: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f440: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f450: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f460: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
f470: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
f480: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
f490: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
f4a0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
f4b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
f4c0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
f4d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f4e0: 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
f4f0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
f500: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
f510: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
f520: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f530: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
f540: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
f550: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
f560: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f570: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
f580: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
f590: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
f5a0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
f5b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
f5c0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
f5d0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
f5e0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
f5f0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
f600: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
f610: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
f620: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
f630: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
f640: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
f650: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f660: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
f670: 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
f680: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
f690: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
f6a0: 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
f6b0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
f6c0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
f6d0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
f6e0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
f6f0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
f700: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
f710: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
f720: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
f730: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
f740: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
f750: 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
f760: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
f770: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
f780: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
f790: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
f7a0: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
f7b0: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
f7c0: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
f7d0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
f7e0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
f7f0: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
f800: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
f810: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
f820: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
f830: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
f840: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
f850: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f860: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
f870: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
f880: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
f890: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
f8a0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
f8b0: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
f8c0: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
f8d0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
f8e0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
f8f0: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
f900: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
f910: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
f920: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
f930: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
f940: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
f950: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
f960: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
f970: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
f980: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
f990: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
f9a0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
f9b0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
f9c0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
f9d0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
f9e0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
f9f0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
fa00: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
fa10: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
fa20: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
fa30: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
fa40: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
fa50: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
fa60: 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
fa70: 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
fa80: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
fa90: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
faa0: 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
fab0: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
fac0: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
fad0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
fae0: 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
faf0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
fb00: 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
fb10: 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
fb20: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
fb30: 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
fb40: 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
fb50: 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
fb60: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
fb70: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
fb80: 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
fb90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
fba0: 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
fbb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
fbc0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
fbd0: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
fbe0: 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
fbf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
fc00: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
fc10: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
fc20: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
fc30: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
fc40: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
fc50: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
fc60: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
fc70: 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
fc80: 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
fc90: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74  cache implemenat
fca0: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
fcb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
fcc0: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
fcd0: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
fce0: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
fcf0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
fd00: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
fd10: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
fd20: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f  _CONFIG_PCACHE o
fd30: 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
fd40: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
fd50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
fd60: 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
fd70: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
fd80: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
fd90: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
fda0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
fdb0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
fdc0: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
fdd0: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
fde0: 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
fdf0: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
fe00: 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
fe10: 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
fe20: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
fe30: 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
fe40: 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
fe50: 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
fe60: 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
fe70: 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
fe80: 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
fe90: 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
fea0: 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
feb0: 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
fec0: 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
fed0: 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
fee0: 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
fef0: 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
ff00: 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
ff10: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
ff20: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
ff30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
ff40: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
ff50: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
ff60: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
ff70: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
ff80: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
ff90: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ffa0: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
ffb0: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
ffc0: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
ffd0: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
ffe0: 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
fff0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
10000 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
10010 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
10020 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
10030 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
10040 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
10050 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
10060 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
10070 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
10080 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
10090 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
100a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
100b0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
100c0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
100d0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
100e0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
100f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
10100 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
10110 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
10120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
10130 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
10140 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10150 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10160 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10170 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
10180 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
10190 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
101a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
101b0 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
101c0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
101d0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
101e0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
101f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
10200 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
10210 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
10220 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
10230 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
10240 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
10250 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
10260 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
10270 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
10280 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
10290 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
102a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
102b0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
102c0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
102d0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
102e0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
102f0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
10300 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
10310 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
10320 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
10330 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
10340 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
10350 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
10360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10370 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
10380 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
10390 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
103a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
103b0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
103c0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
103d0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
103e0 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
103f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
10400 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
10410 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
10420 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
10430 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
10440 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
10450 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
10460 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
10470 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
10480 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
10490 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
104a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
104b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
104c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
104d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
104e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
104f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
10500 61 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61  at 2^12. Reasona
10510 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
10520 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
10530 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
10540 65 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e  e 2^5 through 2^
10550 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  8.</dd>.**.** <d
10560 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10570 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
10580 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10590 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
105a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
105b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
105c0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
105d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
105e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
105f0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
10600 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
10610 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
10620 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
10630 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
10640 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
10650 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
10660 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
10670 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
10680 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
10690 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
106a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
106b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
106c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
106d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
106e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
106f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
10700 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10710 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10720 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10730 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10740 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
10750 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
10760 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
10770 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
10780 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
10790 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
107a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
107b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
107c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
107d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
107e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
107f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
10800 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
10810 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
10820 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10830 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
10840 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10850 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
10860 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
10870 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
10880 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
10890 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
108a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
108b0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
108c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
108d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
108e0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
108f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
10900 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
10910 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
10920 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10930 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10940 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10950 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
10960 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
10970 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
10980 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
10990 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
109a0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
109b0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
109c0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
109d0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
109e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
109f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10a00 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10a10 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10a20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10a30 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
10a40 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
10a50 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
10a60 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
10a70 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
10a80 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
10a90 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
10aa0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
10ab0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
10ac0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ad0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
10ae0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
10af0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
10b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10b10 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
10b20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10b30 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
10b40 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
10b50 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
10b60 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10b70 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
10b80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
10b90 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
10ba0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10bb0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
10bc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
10bd0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
10be0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
10bf0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
10c00 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
10c10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
10c20 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
10c30 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
10c40 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
10c50 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
10c60 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
10c70 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
10c80 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
10c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10ca0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
10cb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
10cc0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
10cd0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
10ce0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
10cf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
10d00 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
10d10 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
10d20 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
10d30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
10d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10d50 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10d60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10d70 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10d80 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
10d90 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
10da0 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
10db0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
10dc0 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
10dd0 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
10de0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
10df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
10e00 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
10e10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
10e20 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
10e30 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
10e40 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10e50 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
10e60 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
10e70 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
10e80 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10e90 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10ea0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10eb0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10ec0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
10ed0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10ee0 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
10ef0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
10f00 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
10f10 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
10f20 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
10f30 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
10f40 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
10f50 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
10f60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
10f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10f80 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
10f90 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
10fa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
10fb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
10fc0 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
10fd0 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
10fe0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
10ff0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
11000 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
11010 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
11020 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
11030 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
11040 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
11050 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
11060 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
11070 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
11080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
11090 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
110a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
110b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
110c0 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
110d0 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
110e0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
110f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11110 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
11120 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
11130 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
11140 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11150 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
11160 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
11170 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
11180 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
11190 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
111a0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
111b0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
111c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
111d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
111e0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
111f0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
11200 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
11210 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
11220 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
11230 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
11240 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
11250 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
11260 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
11270 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
11280 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
11290 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
112a0 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
112b0 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
112c0 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
112d0 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
112e0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
112f0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
11300 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
11310 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
11320 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
11330 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
11340 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
11350 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
11360 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
11370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11380 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
11390 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
113a0 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
113b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
113c0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
113d0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
113e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
113f0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
11400 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
11410 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
11420 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
11430 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
11440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
11450 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
11460 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
11470 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
11480 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
11490 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
114a0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
114b0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
114c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
114d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
114e0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
114f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
11500 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
11510 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
11520 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
11530 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
11540 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
11550 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
11560 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
11570 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
11580 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
11590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
115a0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
115b0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
115c0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
115d0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
115e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
115f0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
11600 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
11610 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
11620 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
11630 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
11640 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
11650 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
11660 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
11670 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
11680 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
11690 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
116a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
116b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
116c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
116d0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
116e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
116f0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
11700 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
11710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11720 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
11730 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
11740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11750 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
11760 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
11770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11780 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
11790 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
117a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
117b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
117c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
117d0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
117e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
117f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11800 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
11810 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
11820 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
11830 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
11840 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
11850 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
11860 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
11870 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
11880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
11890 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
118a0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
118b0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
118c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
118d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
118e0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
118f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11900 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
11910 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
11920 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11930 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
11940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11950 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
11960 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
11970 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
11980 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
11990 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
119a0 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
119b0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
119c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
119d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
119e0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
119f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11a00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
11a10 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
11a20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
11a30 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
11a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11a50 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
11a60 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
11a70 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
11a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11a90 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
11aa0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
11ab0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
11ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
11ad0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
11ae0 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43   int */../*.** C
11af0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
11b00 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
11b10 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
11b20 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
11b30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
11b40 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
11b50 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
11b60 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
11b70 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
11b80 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
11b90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
11ba0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11bb0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
11bc0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
11bd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
11be0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
11bf0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
11c00 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
11c10 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
11c20 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
11c30 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
11c40 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
11c50 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
11c60 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
11c70 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
11c80 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11c90 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11ca0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11cb0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
11cc0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
11cd0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
11ce0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
11cf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
11d00 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
11d10 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
11d20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11d30 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
11d40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
11d50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
11d60 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
11d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11d80 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
11d90 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
11da0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
11db0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
11dc0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
11dd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
11de0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
11df0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11e00 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
11e10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11e20 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
11e30 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
11e40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
11e50 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
11e60 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
11e70 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
11e80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
11e90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
11ea0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
11eb0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11ec0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
11ed0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
11ee0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
11ef0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
11f00 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
11f10 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
11f20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
11f30 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
11f40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11f50 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11f60 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11f70 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
11f80 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
11f90 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
11fa0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
11fb0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
11fc0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
11fd0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11fe0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
11ff0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
12000 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
12010 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12020 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
12030 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
12040 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
12050 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
12060 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
12070 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12080 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
12090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
120a0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
120b0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
120c0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
120d0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
120e0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
120f0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
12100 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
12110 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
12120 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
12130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
12140 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
12150 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
12160 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
12170 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
12180 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12190 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
121a0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
121b0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
121c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
121d0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
121e0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
121f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
12200 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
12210 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
12220 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
12230 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
12240 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
12250 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
12260 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
12270 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
12280 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
12290 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
122a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
122b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
122c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
122d0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
122e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
122f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
12300 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
12310 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
12320 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
12330 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
12340 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
12350 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
12360 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
12370 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12380 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
12390 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
123a0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
123b0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
123c0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
123d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
123e0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
123f0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
12400 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
12410 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12420 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
12430 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
12440 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
12450 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
12460 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
12470 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
12480 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
12490 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
124a0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
124b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
124c0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
124d0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
124e0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
124f0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
12500 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
12510 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
12520 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
12530 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
12540 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
12550 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12560 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
12570 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
12580 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
12590 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
125a0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
125b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
125c0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
125d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
125e0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
125f0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
12600 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
12610 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
12620 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
12630 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
12640 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
12650 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
12660 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
12670 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12680 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
12690 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
126a0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
126b0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
126c0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
126d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
126e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
126f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
12700 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
12710 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
12720 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
12730 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
12740 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
12750 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
12760 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
12770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12780 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12790 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
127a0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
127b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
127c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
127d0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
127e0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
127f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12800 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
12810 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
12820 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
12830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12840 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
12850 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
12860 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
12870 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
12880 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
12890 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
128a0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
128b0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
128c0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
128d0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
128e0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
128f0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
12900 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
12910 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
12920 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
12930 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
12940 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
12950 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
12960 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
12970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12980 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
12990 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
129a0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
129b0 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
129c0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
129d0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
129e0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
129f0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
12a00 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
12a10 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
12a20 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
12a30 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
12a40 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
12a50 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
12a60 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
12a70 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
12a80 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
12a90 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
12aa0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
12ab0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
12ac0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
12ad0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
12ae0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
12af0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
12b00 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
12b10 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
12b20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12b30 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
12b40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
12b50 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
12b60 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
12b70 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
12b80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12b90 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
12ba0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
12bb0 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
12bc0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
12bd0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
12be0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
12bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
12c00 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
12c10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
12c20 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
12c30 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
12c40 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
12c50 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
12c60 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
12c70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
12c80 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
12c90 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
12ca0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
12cb0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
12cc0 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
12cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
12ce0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
12cf0 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
12d00 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
12d10 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
12d20 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
12d30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
12d40 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
12d50 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
12d60 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
12d70 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
12d80 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
12d90 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
12da0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
12db0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
12dc0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
12dd0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
12de0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
12df0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
12e00 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
12e10 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
12e20 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
12e30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
12e40 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
12e50 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
12e60 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
12e70 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
12e80 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
12e90 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
12ea0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
12eb0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
12ec0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
12ed0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
12ee0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
12ef0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
12f00 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
12f10 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
12f20 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
12f30 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
12f40 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
12f50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
12f60 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
12f70 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
12f80 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
12f90 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
12fa0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
12fb0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
12fc0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
12fd0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
12fe0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
12ff0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
13000 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
13010 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
13020 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
13030 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
13040 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
13050 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
13060 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
13070 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
13080 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
13090 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
130a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
130b0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
130c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
130d0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
130e0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
130f0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
13100 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
13110 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
13120 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
13130 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
13140 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
13150 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
13160 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
13170 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
13180 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
13190 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
131a0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
131b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
131c0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
131d0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
131e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
131f0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
13200 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
13210 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
13220 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
13230 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
13240 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
13250 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
13260 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
13270 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
13280 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
13290 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
132a0 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
132b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
132c0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
132d0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
132e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
132f0 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
13300 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
13310 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
13320 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
13330 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
13340 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
13350 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
13360 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
13370 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
13380 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
13390 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
133a0 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
133b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
133c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
133d0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
133e0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
133f0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
13400 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
13410 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
13420 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
13430 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
13440 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
13450 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
13460 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
13470 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
13480 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
13490 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
134a0 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
134b0 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
134c0 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
134d0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
134e0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
134f0 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
13500 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
13510 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
13520 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
13530 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
13540 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
13550 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
13560 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
13570 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
13580 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
13590 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
135a0 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
135b0 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
135c0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
135d0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
135e0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
135f0 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
13600 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
13610 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
13620 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
13630 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
13640 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
13650 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
13660 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
13670 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
13680 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
13690 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
136a0 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
136b0 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
136c0 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
136d0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
136e0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
136f0 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
13700 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
13710 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
13720 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
13730 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
13740 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
13750 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
13760 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
13770 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
13780 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
13790 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
137a0 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
137b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
137c0 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
137d0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
137e0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
137f0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
13800 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
13810 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
13820 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
13830 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
13840 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
13850 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
13860 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
13870 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
13880 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
138a0 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
138b0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
138c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
138d0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
138e0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
138f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
13900 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13910 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
13920 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
13930 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
13940 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
13950 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
13960 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
13970 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
13980 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
13990 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
139a0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
139b0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
139c0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
139d0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
139e0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
139f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
13a00 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
13a10 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
13a20 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
13a30 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
13a40 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13a50 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
13a60 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
13a70 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
13a80 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
13a90 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
13aa0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
13ab0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
13ac0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
13ad0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
13ae0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
13af0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
13b00 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
13b10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
13b20 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
13b30 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
13b40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
13b50 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
13b60 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
13b70 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
13b80 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
13b90 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
13ba0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
13bb0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
13bc0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
13bd0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
13be0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
13bf0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
13c00 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
13c10 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
13c20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
13c30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
13c40 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
13c50 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
13c60 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
13c70 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
13c80 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
13c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13ca0 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
13cb0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
13cc0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
13cd0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
13ce0 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
13cf0 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
13d00 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
13d10 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
13d20 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
13d30 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
13d40 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
13d50 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
13d60 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
13d70 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
13d80 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
13d90 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
13da0 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
13db0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
13dc0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
13dd0 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
13de0 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
13df0 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
13e00 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
13e10 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
13e20 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
13e30 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
13e40 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
13e50 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
13e60 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
13e70 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
13e80 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
13e90 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
13ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
13eb0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
13ec0 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
13ed0 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
13ee0 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
13ef0 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
13f00 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
13f10 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
13f20 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
13f30 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
13f40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
13f50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
13f60 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
13f70 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
13f80 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
13f90 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
13fa0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
13fb0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
13fc0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
13fd0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
13fe0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
13ff0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
14000 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
14010 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
14020 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
14030 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
14040 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
14050 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
14060 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
14070 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
14080 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
14090 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
140a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
140b0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
140c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
140d0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
140e0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
140f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14100 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
14110 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
14120 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
14130 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
14140 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
14150 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
14160 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
14170 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
14180 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
14190 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
141a0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
141b0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
141c0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
141d0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
141e0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
141f0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
14200 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
14210 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
14220 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
14230 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
14240 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
14250 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
14260 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
14270 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
14280 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
14290 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
142a0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
142b0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
142c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
142d0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
142e0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
142f0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
14300 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14310 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
14320 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
14330 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
14340 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
14350 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
14360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
14370 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
14380 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
14390 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
143a0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
143b0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
143c0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
143d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
143e0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
143f0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
14400 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
14410 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14420 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
14430 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
14440 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
14450 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
14460 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
14470 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
14480 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
14490 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
144a0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
144b0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
144c0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
144d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
144e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
144f0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
14500 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
14510 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
14520 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
14530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
14540 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14550 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
14560 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
14570 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
14580 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
14590 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
145a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
145b0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
145c0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
145d0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
145e0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
145f0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
14600 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
14610 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
14620 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14630 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
14640 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
14650 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
14660 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
14670 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
14680 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
14690 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
146a0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
146b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
146c0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
146d0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
146e0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
146f0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
14700 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
14710 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
14720 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
14730 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
14740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
14750 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
14760 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
14770 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14780 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
14790 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
147a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
147b0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
147c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
147d0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
147e0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
147f0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
14800 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
14810 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
14820 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
14830 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
14840 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
14850 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
14860 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
14870 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
14880 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
14890 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
148a0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
148b0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
148c0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
148d0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
148e0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
148f0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
14900 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
14910 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
14920 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
14930 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
14940 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
14950 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
14960 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
14970 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
14980 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
14990 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
149a0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
149b0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
149c0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
149d0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
149e0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
149f0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
14a00 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
14a10 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
14a20 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
14a30 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
14a40 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
14a50 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
14a60 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
14a70 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
14a80 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
14a90 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
14aa0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
14ab0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
14ac0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
14ad0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
14ae0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
14af0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
14b00 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
14b10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
14b20 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
14b30 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
14b40 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
14b50 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
14b60 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
14b70 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
14b80 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
14b90 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
14ba0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
14bb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14bc0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
14bd0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
14be0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
14bf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
14c00 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
14c10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
14c20 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
14c30 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
14c40 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
14c50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
14c60 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
14c70 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
14c80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
14c90 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
14ca0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
14cb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14cc0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
14cd0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
14ce0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
14cf0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
14d00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
14d10 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
14d20 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
14d30 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
14d40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
14d50 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
14d60 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
14d70 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
14d80 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
14d90 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
14da0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
14db0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
14dc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
14dd0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
14de0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
14df0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
14e00 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
14e10 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
14e20 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
14e30 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
14e40 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
14e50 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
14e60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
14e70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
14e80 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
14e90 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
14ea0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14eb0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
14ec0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
14ed0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
14ee0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
14ef0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
14f00 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
14f10 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
14f20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
14f30 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
14f40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
14f50 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
14f60 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
14f70 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
14f80 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
14f90 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
14fa0 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
14fb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
14fc0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
14fd0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
14fe0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
14ff0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
15000 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
15010 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
15020 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
15030 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
15040 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
15050 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
15060 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
15070 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
15080 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
15090 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
150a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
150b0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
150c0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
150d0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
150e0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
150f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
15100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
15110 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
15120 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
15130 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
15140 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
15150 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
15160 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
15170 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
15180 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
15190 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
151a0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
151b0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
151c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
151d0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
151e0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
151f0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
15200 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
15210 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
15220 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
15230 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
15240 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
15250 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
15260 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
15270 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
15280 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
15290 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
152a0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
152b0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
152c0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
152d0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
152e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
152f0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
15300 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
15310 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
15320 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
15330 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
15340 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
15350 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
15360 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
15370 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
15380 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
15390 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
153a0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
153b0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
153c0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
153d0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
153e0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
153f0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
15400 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
15410 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
15420 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
15430 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
15440 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
15450 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
15460 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
15470 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
15480 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
15490 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
154a0 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
154b0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
154c0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
154d0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
154e0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
154f0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
15500 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
15510 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
15520 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
15530 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
15540 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
15550 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
15560 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
15570 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
15580 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
15590 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
155a0 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
155b0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
155c0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
155d0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
155e0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
155f0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
15600 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
15610 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
15620 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
15630 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
15640 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
15650 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
15660 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
15670 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
15680 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
15690 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
156a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
156b0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
156c0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
156d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
156e0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
156f0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
15700 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
15710 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
15720 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
15730 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
15740 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
15750 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
15760 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
15770 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
15780 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
15790 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
157a0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
157b0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
157c0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
157d0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
157e0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
157f0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
15800 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
15810 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
15820 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
15830 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
15840 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
15850 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
15860 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
15870 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
15880 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
15890 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
158a0 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
158b0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
158c0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
158d0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
158e0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
158f0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
15900 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
15910 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
15920 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
15930 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
15940 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
15950 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
15960 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
15970 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
15980 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
15990 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
159a0 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
159b0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
159c0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
159d0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
159e0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
159f0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
15a00 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
15a10 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
15a20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
15a30 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
15a40 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
15a50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
15a60 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
15a70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
15a80 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
15a90 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
15aa0 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
15ab0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
15ac0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
15ad0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
15ae0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
15af0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
15b00 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
15b10 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
15b20 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
15b30 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
15b40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
15b50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
15b60 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
15b70 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
15b80 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
15b90 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
15ba0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
15bb0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
15bc0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
15bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15be0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
15bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15c00 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
15c10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15c20 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
15c30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
15c40 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
15c50 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
15c60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15c70 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
15c80 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
15c90 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
15ca0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
15cb0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
15cc0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
15cd0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
15ce0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
15cf0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
15d00 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
15d10 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
15d20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
15d30 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
15d40 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
15d50 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
15d60 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
15d70 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
15d80 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
15d90 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
15da0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
15db0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
15dc0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
15dd0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
15de0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
15df0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
15e00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
15e10 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
15e20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
15e30 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
15e40 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
15e50 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
15e60 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
15e70 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
15e80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
15e90 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
15ea0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
15eb0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
15ec0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
15ed0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
15ee0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
15ef0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
15f00 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
15f10 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
15f20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
15f30 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
15f40 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
15f50 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
15f60 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
15f70 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
15f80 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
15f90 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
15fa0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
15fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15fc0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
15fd0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
15fe0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
15ff0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
16000 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
16010 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
16020 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
16030 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
16040 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
16050 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
16060 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
16070 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
16080 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
16090 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
160a0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
160b0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
160c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
160d0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
160e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
160f0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
16100 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
16110 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
16120 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
16130 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
16140 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
16150 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
16160 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
16170 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
16180 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
16190 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
161a0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
161b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
161c0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
161d0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
161e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
161f0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
16200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
16210 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
16220 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
16230 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
16240 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
16250 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
16260 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
16270 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
16280 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
16290 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
162a0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
162b0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
162c0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
162d0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
162e0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
162f0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
16300 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
16310 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
16320 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
16330 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
16340 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
16350 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
16360 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
16370 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
16380 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
16390 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
163a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
163b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
163c0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
163d0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
163e0 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
163f0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
16400 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
16410 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
16420 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
16430 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
16440 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
16450 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
16460 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
16470 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
16480 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
16490 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
164a0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
164b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
164c0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
164d0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
164e0 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
164f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
16500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16510 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
16520 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
16530 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
16540 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
16550 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
16560 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
16570 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
16580 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
16590 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
165a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
165b0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
165c0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
165d0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
165e0 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
165f0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
16600 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
16610 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
16620 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
16630 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
16640 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
16650 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
16660 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
16670 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
16680 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16690 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
166a0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
166b0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
166c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
166d0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
166e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
166f0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
16700 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16710 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
16720 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16730 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
16740 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
16750 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
16760 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
16770 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
16780 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
16790 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
167a0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
167b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
167c0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
167d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
167e0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
167f0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
16800 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
16810 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
16820 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
16830 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16840 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
16850 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
16860 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
16870 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
16880 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
16890 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
168a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
168b0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
168c0 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
168d0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
168e0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
168f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16900 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
16910 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
16920 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
16930 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
16940 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
16950 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
16960 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
16970 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
16980 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
169a0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
169b0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
169c0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
169d0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
169e0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
169f0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
16a00 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
16a10 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
16a20 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
16a30 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
16a40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
16a50 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
16a60 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
16a70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16a80 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
16a90 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
16aa0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
16ab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
16ac0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
16ad0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
16ae0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
16af0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
16b00 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
16b10 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
16b20 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
16b30 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
16b40 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
16b50 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
16b60 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
16b70 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
16b80 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
16b90 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
16ba0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
16bb0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
16bc0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
16bd0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
16be0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
16bf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
16c00 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
16c10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16c20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16c30 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
16c40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
16c50 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
16c60 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
16c70 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
16c80 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
16c90 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
16ca0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
16cb0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
16cc0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
16cd0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
16ce0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
16cf0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
16d00 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16d10 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
16d20 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
16d30 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
16d40 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
16d50 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
16d60 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
16d70 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
16d80 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
16d90 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
16da0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
16db0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
16dc0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
16dd0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
16de0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
16df0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
16e00 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
16e10 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
16e20 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
16e30 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
16e40 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
16e50 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
16e60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16e70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
16e80 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
16e90 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
16ea0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
16eb0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
16ec0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
16ed0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
16ee0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
16ef0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
16f00 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
16f10 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
16f20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
16f30 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
16f40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
16f50 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
16f60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
16f70 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
16f80 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
16f90 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
16fa0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
16fb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
16fc0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16fd0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
16fe0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
16ff0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
17000 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
17010 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
17020 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
17030 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
17040 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
17050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17060 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
17070 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
17080 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
17090 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
170a0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
170b0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
170c0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
170d0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
170e0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
170f0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
17100 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
17110 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
17120 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
17130 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17140 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
17150 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
17160 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
17170 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
17180 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
17190 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
171a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
171b0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
171c0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
171d0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
171e0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
171f0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
17200 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
17210 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
17220 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
17230 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
17240 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
17250 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
17260 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17270 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
17280 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
17290 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
172a0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
172b0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
172c0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
172d0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
172e0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
172f0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
17300 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
17310 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
17320 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
17330 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
17340 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
17350 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
17360 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
17370 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
17380 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
17390 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
173a0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
173b0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
173c0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
173d0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
173e0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
173f0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
17400 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
17410 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
17420 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
17430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17440 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
17450 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
17460 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
17470 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
17480 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
17490 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
174a0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
174b0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
174c0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
174d0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
174e0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
174f0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
17500 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
17510 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
17520 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
17530 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
17540 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
17550 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
17560 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
17570 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
17580 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
17590 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
175a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
175b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
175c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
175d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
175e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
175f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
17600 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
17610 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
17620 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
17630 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
17640 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
17650 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
17660 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
17670 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
17680 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
17690 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
176a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
176b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
176c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
176d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
176e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
176f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17700 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
17710 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
17720 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
17730 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
17740 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17750 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
17760 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
17770 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17780 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
17790 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
177a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
177b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
177c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
177d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
177e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
177f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
17800 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
17810 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
17820 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
17830 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
17840 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
17850 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
17860 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
17870 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
17880 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
17890 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
178a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
178b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
178c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
178d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
178e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
178f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
17900 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
17910 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
17920 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
17930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
17940 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
17950 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17960 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
17970 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
17980 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17990 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
179a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
179b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
179c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
179d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
179e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
179f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
17a00 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
17a10 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
17a20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
17a30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
17a40 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
17a50 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
17a60 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
17a70 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
17a80 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
17a90 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
17aa0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
17ab0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
17ac0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
17ad0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
17ae0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
17af0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
17b00 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
17b10 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
17b20 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
17b30 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
17b40 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
17b50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17b60 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
17b70 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
17b80 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
17b90 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
17ba0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
17bb0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
17bc0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
17bd0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
17be0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
17bf0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
17c00 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
17c10 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
17c20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
17c30 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
17c40 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
17c50 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
17c60 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
17c70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
17c80 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
17c90 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
17ca0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
17cb0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
17cc0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
17cd0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
17ce0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
17cf0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
17d00 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
17d10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
17d20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
17d30 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
17d40 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
17d50 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
17d60 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
17d70 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
17d80 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
17d90 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
17da0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
17db0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
17dc0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
17dd0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
17de0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
17df0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
17e00 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
17e10 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
17e20 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
17e30 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
17e40 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
17e50 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
17e60 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
17e70 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
17e80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17e90 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
17ea0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
17eb0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
17ec0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
17ed0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
17ee0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
17ef0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
17f00 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
17f10 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
17f20 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
17f30 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
17f40 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
17f50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17f60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
17f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
17f80 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
17f90 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
17fa0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
17fb0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
17fc0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
17fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17fe0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
17ff0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
18000 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
18010 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
18020 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
18030 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
18040 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
18050 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
18060 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
18070 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18080 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
18090 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
180a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
180b0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
180c0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
180d0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
180e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
180f0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
18100 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
18110 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
18120 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
18130 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
18140 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
18150 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
18160 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
18170 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
18180 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
18190 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
181a0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
181b0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
181c0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
181d0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
181e0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
181f0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
18200 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
18210 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
18220 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
18230 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
18240 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
18250 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
18260 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
18270 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
18280 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
18290 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
182a0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
182b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
182c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
182d0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
182e0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
182f0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
18300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
18310 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
18320 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
18330 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
18340 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
18350 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
18360 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
18370 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
18380 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
18390 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
183a0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
183b0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
183c0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
183d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
183e0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
183f0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
18400 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
18410 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
18420 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
18430 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
18440 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
18450 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
18460 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
18470 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
18480 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
18490 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
184a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
184b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
184c0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
184d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
184e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
184f0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
18500 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
18510 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
18520 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
18530 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
18540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
18550 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
18560 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
18570 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
18580 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
18590 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
185a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
185b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
185c0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
185d0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
185e0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
185f0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
18600 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
18610 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
18620 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
18630 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
18640 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
18650 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
18660 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
18670 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
18680 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
18690 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
186a0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
186b0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
186c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
186d0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
186e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
186f0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
18700 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
18710 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
18720 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
18730 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
18740 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18750 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
18760 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
18770 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
18780 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
18790 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
187a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
187b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
187c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
187d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
187e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
187f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
18800 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
18810 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
18820 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
18830 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
18840 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
18850 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
18860 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
18870 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
18880 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
18890 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
188a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
188b0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
188c0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
188d0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
188e0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
188f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
18900 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
18910 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
18920 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
18930 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
18940 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
18950 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
18960 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
18970 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
18980 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
18990 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
189a0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
189b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
189c0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
189d0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
189e0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
189f0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
18a00 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
18a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
18a20 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
18a30 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
18a40 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
18a50 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
18a60 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
18a70 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
18a80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
18a90 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
18aa0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
18ab0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
18ac0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
18ad0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
18ae0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
18af0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
18b00 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
18b10 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
18b20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
18b30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18b40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
18b50 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
18b60 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
18b70 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
18b80 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
18b90 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
18ba0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
18bb0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
18bc0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
18bd0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
18be0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
18bf0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
18c00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
18c10 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
18c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
18c30 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
18c40 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
18c50 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
18c60 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
18c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18c80 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
18c90 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
18ca0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
18cb0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
18cc0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
18cd0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
18ce0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
18cf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18d00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
18d10 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
18d20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
18d30 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
18d40 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
18d50 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
18d60 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
18d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
18d80 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18d90 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
18da0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
18db0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
18dc0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
18dd0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
18de0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
18df0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
18e00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18e10 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
18e20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
18e30 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
18e40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
18e50 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
18e60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
18e70 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
18e80 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
18e90 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
18ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18eb0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
18ec0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
18ed0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
18ee0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
18ef0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
18f00 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
18f10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
18f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
18f30 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
18f40 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
18f50 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
18f60 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
18f70 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
18f80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18f90 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
18fa0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
18fb0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
18fc0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
18fd0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
18fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
18ff0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
19000 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
19010 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
19020 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
19030 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
19040 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
19050 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
19060 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
19070 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
19080 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
19090 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
190a0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
190b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
190c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
190d0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
190e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
190f0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
19100 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
19110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
19120 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
19130 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
19140 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
19150 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
19160 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
19170 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
19180 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
19190 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
191a0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
191b0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
191c0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
191d0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
191e0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
191f0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
19200 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
19210 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
19220 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
19230 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
19240 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
19250 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
19260 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
19270 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
19280 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
19290 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
192a0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
192b0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
192c0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
192d0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
192e0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
192f0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
19300 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
19310 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
19320 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
19330 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
19340 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
19350 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
19360 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
19370 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
19380 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
19390 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
193a0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
193b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
193c0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
193d0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
193e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
193f0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
19400 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
19410 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
19420 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
19430 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
19440 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
19450 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
19460 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
19470 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
19480 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
19490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
194a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
194b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
194c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
194d0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
194e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
194f0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
19500 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
19510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19520 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
19530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19540 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
19550 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
19560 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
19570 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
19580 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
19590 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
195a0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
195b0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
195c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
195d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
195e0 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
195f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19600 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
19610 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
19620 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
19630 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
19640 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
19650 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
19660 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
19670 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
19680 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19690 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
196a0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
196b0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
196c0 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
196d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
196e0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
196f0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
19700 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
19710 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
19720 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
19730 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
19740 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
19750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
19760 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
19770 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
19780 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
19790 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
197a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
197b0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
197c0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
197d0 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
197e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
197f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
19800 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
19810 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
19820 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
19830 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
19840 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
19850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
19860 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
19870 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
19880 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
19890 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
198a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
198b0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
198c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
198d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
198e0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
198f0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
19900 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
19910 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
19920 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19930 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
19940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19950 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
19960 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
19970 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
19980 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
19990 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
199a0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
199b0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
199c0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
199d0 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
199e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
199f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19a00 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
19a10 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
19a20 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
19a30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
19a40 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
19a50 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
19a60 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
19a70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
19a80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
19a90 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
19aa0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
19ab0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
19ac0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
19ad0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
19ae0 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
19af0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
19b00 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
19b10 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
19b20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
19b30 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
19b40 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
19b50 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
19b60 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
19b70 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
19b80 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
19b90 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
19ba0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
19bb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19bc0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
19bd0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
19be0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
19bf0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
19c00 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
19c10 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
19c20 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
19c30 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
19c40 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
19c50 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
19c60 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
19c70 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
19c80 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
19c90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
19ca0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
19cb0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
19cc0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
19cd0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
19ce0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
19cf0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
19d00 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
19d10 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
19d20 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
19d30 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
19d40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
19d50 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
19d60 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
19d70 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
19d80 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
19d90 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
19da0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
19db0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
19dc0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
19dd0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
19de0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
19df0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19e00 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
19e10 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
19e20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
19e30 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
19e40 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
19e50 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
19e60 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
19e70 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
19e80 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
19e90 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
19ea0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
19eb0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
19ec0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
19ed0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
19ee0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
19ef0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
19f00 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
19f10 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
19f20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
19f30 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
19f40 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
19f50 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
19f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
19f70 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
19f80 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
19f90 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
19fa0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
19fb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
19fc0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
19fd0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
19fe0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
19ff0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1a000 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1a010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a020 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1a030 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1a040 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1a050 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1a060 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1a070 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1a080 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1a090 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1a0a0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1a0b0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1a0c0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1a0d0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1a0e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1a0f0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1a100 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1a110 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1a120 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1a130 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1a140 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1a150 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1a160 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1a170 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1a180 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1a190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a1a0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1a1b0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1a1c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a1d0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1a1e0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1a1f0 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1a200 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1a210 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1a220 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1a230 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1a240 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1a250 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1a260 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1a270 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1a280 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1a290 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1a2a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1a2b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1a2c0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1a2d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1a2e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1a2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a300 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a310 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1a320 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1a330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a340 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1a350 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1a360 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1a370 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1a380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a390 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1a3a0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1a3b0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1a3c0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1a3d0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1a3e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1a3f0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1a400 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1a410 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1a420 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1a430 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1a440 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1a450 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1a460 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1a470 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1a480 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1a490 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1a4a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a4b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1a4c0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1a4d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1a4e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1a4f0 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1a500 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1a510 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1a520 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1a530 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1a540 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1a550 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1a560 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1a570 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1a580 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a5a0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1a5b0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1a5c0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1a5d0 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
1a5e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a5f0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1a600 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1a610 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1a620 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a630 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1a640 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1a650 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1a660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a670 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1a680 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1a690 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1a6a0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a6b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a6c0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1a6d0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1a6e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1a6f0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1a700 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1a710 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1a720 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1a730 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1a740 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1a750 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1a760 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a770 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1a780 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1a790 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1a7a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1a7b0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1a7c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1a7d0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1a7e0 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1a7f0 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1a800 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1a810 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1a820 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1a830 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1a840 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1a850 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1a860 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1a870 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1a880 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1a890 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1a8a0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1a8b0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1a8c0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1a8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1a8e0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1a8f0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1a900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a910 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a920 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a930 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a940 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a950 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a960 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a970 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a980 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a9a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a9b0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a9c0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a9d0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a9e0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a9f0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1aa00 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1aa10 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1aa20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1aa30 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1aa40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1aa50 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1aa60 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1aa70 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1aa80 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1aa90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1aaa0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1aab0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1aac0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1aad0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1aae0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1aaf0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1ab00 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1ab10 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1ab20 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1ab30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1ab40 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1ab50 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1ab60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ab70 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1ab80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1ab90 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1aba0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1abb0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1abc0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1abd0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1abe0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1abf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1ac00 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1ac10 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1ac20 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1ac30 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1ac40 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1ac50 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1ac60 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1ac70 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1ac80 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1ac90 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1aca0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1acb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1acc0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1acd0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1ace0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acf0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1ad00 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1ad10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ad20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ad30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ad40 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1ad50 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1ad60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ad70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ad80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ad90 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1ada0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1adb0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1adc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1add0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ade0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1adf0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1ae00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ae10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ae20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ae30 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1ae40 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1ae50 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1ae60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ae70 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ae80 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1ae90 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1aea0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1aeb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aec0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1aed0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1aee0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1aef0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1af00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1af10 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1af20 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1af30 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1af40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1af50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1af60 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1af70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1af80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1af90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1afa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1afb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1afc0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1afd0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1afe0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1aff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b000 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1b010 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1b020 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b050 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1b060 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1b070 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b080 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1b090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b0a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1b0b0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1b0c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b0d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b0e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b0f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1b100 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1b110 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1b120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b140 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1b150 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1b160 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1b170 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b190 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1b1a0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1b1b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1b1c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b1d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1e0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1b1f0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1b200 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1b210 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1b230 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1b240 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1b250 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b260 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1b280 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1b290 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1b2a0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1b2b0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1b2c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1b2d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1b2e0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1b2f0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1b300 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1b310 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1b320 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1b330 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1b340 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1b350 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b360 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1b370 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1b380 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1b390 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1b3a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b3b0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1b3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b3d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1b3e0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1b3f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b400 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1b410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1b420 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1b430 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b440 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b450 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1b460 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1b470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1b480 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1b490 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b4a0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1b4b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1b4c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1b4d0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1b4e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b4f0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1b500 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1b510 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b520 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b530 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b540 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1b550 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1b560 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b570 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b580 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b590 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1b5a0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1b5b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b5c0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1b5d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b5e0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1b5f0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1b600 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b610 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1b620 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b630 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1b640 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1b650 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1b660 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1b670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b680 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1b690 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1b6a0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1b6b0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1b6c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b6d0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1b6e0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1b6f0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1b700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b710 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1b720 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1b730 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b740 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1b750 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1b760 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1b770 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1b780 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1b790 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1b7a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1b7b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1b7c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1b7d0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1b7e0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1b7f0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1b800 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1b810 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1b820 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1b830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b840 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1b850 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1b860 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1b870 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1b880 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1b890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1b8a0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1b8b0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1b8c0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1b8d0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1b8e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1b8f0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1b900 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1b910 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1b920 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1b930 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1b940 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1b950 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1b960 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1b970 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1b980 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1b990 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b9a0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b9b0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1b9c0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b9d0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1b9e0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1b9f0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1ba00 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1ba10 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1ba20 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1ba30 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1ba40 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1ba50 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1ba60 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1ba70 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1ba80 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1ba90 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1baa0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1bab0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1bac0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1bad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1bae0 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1baf0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1bb00 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1bb10 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1bb20 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1bb30 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1bb40 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1bb50 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1bb60 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1bb70 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1bb80 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1bb90 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1bba0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1bbb0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1bbc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1bbd0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1bbe0 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1bbf0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1bc00 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1bc10 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1bc20 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1bc30 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1bc40 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1bc50 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1bc60 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1bc70 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1bc80 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1bc90 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1bca0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1bcb0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1bcc0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1bcd0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1bce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1bcf0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1bd00 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1bd10 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1bd20 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1bd30 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1bd40 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1bd50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1bd60 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1bd70 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1bd80 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1bd90 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1bda0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1bdb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1bdc0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1bdd0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1bde0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bdf0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1be00 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1be10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1be20 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1be30 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1be40 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1be50 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1be60 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1be70 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1be80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1be90 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1bea0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1beb0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1bec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1bed0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1bee0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1bef0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1bf00 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1bf10 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
1bf20 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
1bf30 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
1bf40 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1bf50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1bf60 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1bf70 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1bf80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bf90 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1bfa0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1bfb0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1bfc0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1bfd0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1bfe0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1bff0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1c000 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1c010 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1c020 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1c030 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1c040 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1c050 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1c060 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1c070 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1c080 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1c090 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1c0a0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1c0b0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1c0c0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1c0d0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1c0e0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1c0f0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1c100 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1c110 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c120 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1c130 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1c140 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1c150 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1c160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1c170 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1c180 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1c190 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c1b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1c1c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1c1d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1c1e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c1f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1c200 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1c210 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1c220 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
1c230 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c240 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c250 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1c260 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1c270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1c280 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1c290 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1c2a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1c2b0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1c2c0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1c2d0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1c2e0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1c2f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1c300 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1c310 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1c320 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1c330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1c340 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1c350 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1c360 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1c370 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1c380 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1c390 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1c3a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c3b0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1c3c0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1c3d0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1c3e0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1c3f0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1c400 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1c410 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1c420 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1c430 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1c440 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1c450 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1c460 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1c470 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1c480 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1c490 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1c4a0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1c4b0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1c4c0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1c4d0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1c4e0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1c4f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1c500 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1c510 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1c520 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1c530 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1c540 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c550 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1c560 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1c570 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1c580 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1c590 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1c5a0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1c5b0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1c5c0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1c5d0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1c5e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1c5f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1c600 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1c610 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1c620 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1c630 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1c640 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1c650 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1c660 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1c670 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1c680 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1c690 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1c6a0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1c6b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1c6c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1c6d0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1c6e0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1c6f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1c700 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1c710 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1c720 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1c730 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1c740 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1c750 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1c760 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1c770 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1c780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c790 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1c7a0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1c7b0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1c7c0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1c7d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1c7e0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1c7f0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1c800 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1c810 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1c820 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1c830 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1c840 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1c850 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1c860 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1c870 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1c880 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1c890 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1c8a0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1c8b0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1c8c0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1c8d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1c8e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1c8f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  .** and/or [SQLI
1c900 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1c910 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  ACHE] flags:)^.*
1c920 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1c930 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1c940 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1c950 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1c960 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1c970 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1c980 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1c990 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1c9a0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1c9b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1c9c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c9d0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1c9e0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1c9f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1ca00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1ca10 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1ca20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1ca30 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1ca40 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1ca50 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1ca60 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1ca70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1ca80 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1ca90 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1caa0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1cab0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1cac0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1cad0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1cae0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1caf0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1cb00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1cb10 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1cb20 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1cb30 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1cb40 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1cb50 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1cb60 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1cb70 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1cb80 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1cb90 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1cba0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1cbb0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cbc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1cbd0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1cbe0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1cbf0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1cc00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1cc10 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1cc20 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1cc30 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1cc40 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74  bove or one of t
1cc50 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  he combinations 
1cc60 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62  shown above comb
1cc70 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ined.** with the
1cc80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1cc90 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1cca0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1ccb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1ccc0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e  _SHAREDCACHE] an
1ccd0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1cce0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1ccf0 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
1cd00 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1cd10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1cd20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1cd30 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1cd40 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1cd50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cd60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1cd70 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1cd80 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1cd90 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1cda0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1cdb0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1cdc0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1cdd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1cde0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1cdf0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1ce00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1ce10 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1ce20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ce30 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1ce40 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1ce50 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1ce60 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1ce70 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1ce80 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1ce90 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1cea0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1ceb0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1cec0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1ced0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1cee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1cef0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1cf00 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1cf10 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1cf20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1cf30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1cf40 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1cf50 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1cf60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1cf70 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1cf80 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1cf90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1cfa0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1cfb0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1cfc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1cfd0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1cfe0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1cff0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1d000 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1d010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1d020 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1d030 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d040 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1d050 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1d060 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1d070 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1d080 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1d090 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1d0a0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1d0b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1d0c0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1d0d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1d0e0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1d0f0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1d100 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d110 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1d120 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
1d130 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1d140 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1d150 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1d160 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1d170 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1d180 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1d190 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1d1a0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1d1b0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1d1c0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1d1d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d1e0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1d1f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d200 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d210 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1d220 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1d230 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1d240 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1d250 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1d260 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1d270 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1d280 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1d290 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1d2a0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1d2b0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1d2c0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1d2d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1d2e0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1d2f0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1d300 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1d310 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1d320 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1d330 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1d340 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1d350 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1d360 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1d370 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1d380 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1d390 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1d3a0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1d3b0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1d3c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d3d0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1d3e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 55 52 49 20 66  .**.** ^If URI f
1d3f0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1d400 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1d410 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
1d420 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1d430 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
1d440 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
1d450 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
1d460 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
1d470 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
1d480 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1d490 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
1d4a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
1d4b0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 69  RI] flag is.** i
1d4c0 73 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  s set in the fou
1d4d0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1d4e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d4f0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
1d500 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
1d510 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
1d520 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
1d530 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
1d540 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
1d550 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
1d560 68 6f 64 2e 20 0a 2a 2a 0a 2a 2a 20 55 52 49 20  hod. .**.** URI 
1d570 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
1d580 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
1d590 6f 20 52 46 43 20 31 37 33 38 2e 20 49 66 20 74  o RFC 1738. If t
1d5a0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1d5b0 61 6e 0a 2a 2a 20 27 61 75 74 68 6f 72 69 74 79  an.** 'authority
1d5c0 27 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  ', then it must 
1d5d0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
1d5e0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
1d5f0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
1d600 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
1d610 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
1d620 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
1d630 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
1d640 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
1d650 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
1d660 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 27  e caller. ^The '
1d670 66 72 61 67 6d 65 6e 74 27 20 63 6f 6d 70 6f 6e  fragment' compon
1d680 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
1d690 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
1d6a0 20 61 6c 77 61 79 73 20 69 67 6e 6f 72 65 64 2e   always ignored.
1d6b0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
1d6c0 73 65 73 20 74 68 65 20 27 70 61 74 68 27 20 63  ses the 'path' c
1d6d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
1d6e0 55 52 49 20 61 73 20 74 68 65 20 70 61 74 68 20  URI as the path 
1d6f0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1d700 66 69 6c 65 0a 2a 2a 20 74 6f 20 6f 70 65 6e 2e  file.** to open.
1d710 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
1d720 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
1d730 63 68 61 72 61 63 74 65 72 2c 20 74 68 65 6e 20  character, then 
1d740 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
1d750 64 20 61 73 0a 2a 2a 20 61 6e 20 61 62 73 6f 6c  d as.** an absol
1d760 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 69 74  ute path. ^If it
1d770 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
1d780 77 69 74 68 20 61 20 27 2f 27 2c 20 69 74 20 69  with a '/', it i
1d790 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1d7a0 20 61 20 0a 2a 2a 20 72 65 6c 61 74 69 76 65 20   a .** relative 
1d7b0 70 61 74 68 2e 20 5e 4f 6e 20 77 69 6e 64 6f 77  path. ^On window
1d7c0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
1d7d0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
1d7e0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
1d7f0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
1d800 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
1d810 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 71  :")..**.** The q
1d820 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1d830 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
1d840 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
1d850 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
1d860 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
1d870 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
1d880 6f 72 20 62 79 20 61 20 5b 73 71 6c 69 74 65 33  or by a [sqlite3
1d890 5f 76 66 73 20 7c 20 63 75 73 74 6f 6d 20 56 46  _vfs | custom VF
1d8a0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1d8b0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1d8c0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1d8d0 6f 77 69 6e 67 20 66 6f 75 72 20 71 75 65 72 79  owing four query
1d8e0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
1d8f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1d900 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
1d910 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
1d920 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
1d930 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
1d940 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
1d950 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
1d960 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
1d970 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1d980 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
1d990 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
1d9a0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
1d9b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
1d9c0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
1d9d0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1d9e0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
1d9f0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
1da00 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
1da10 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
1da20 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
1da30 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
1da40 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
1da50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1da60 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
1da70 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
1da80 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
1da90 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
1daa0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
1dab0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
1dac0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
1dad0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
1dae0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1daf0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1db00 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
1db10 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
1db20 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
1db30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1db40 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
1db50 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a  "ro", "rw" or.**
1db60 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65       "rwc". Atte
1db70 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
1db80 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
1db90 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29  lue is an error)
1dba0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
1dbb0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
1dbc0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1dbd0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1dbe0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
1dbf0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
1dc00 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
1dc10 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1dc20 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
1dc30 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
1dc40 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
1dc50 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
1dc60 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
1dc70 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1dc80 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
1dc90 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
1dca0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1dcb0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
1dcc0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
1dcd0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
1dce0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
1dcf0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
1dd00 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
1dd10 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
1dd20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
1dd30 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
1dd40 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1dd50 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
1dd60 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1dd70 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
1dd80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1dd90 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  E. ^If sqlite3_o
1dda0 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20  pen_v2() is .** 
1ddb0 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20      used, it is 
1ddc0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
1ddd0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20  ify a value for 
1dde0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
1ddf0 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20  er that is .**  
1de00 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74     less restrict
1de10 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
1de20 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
1de30 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74  lags passed as t
1de40 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20  he third .**    
1de50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1de60 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
1de70 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
1de80 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1de90 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1dea0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
1deb0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
1dec0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
1ded0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
1dee0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1def0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
1df00 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1df10 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
1df20 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
1df30 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
1df40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1df50 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
1df60 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
1df70 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
1df80 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
1df90 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
1dfa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1dfb0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
1dfc0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
1dfd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1dfe0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
1dff0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
1e000 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
1e010 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
1e020 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
1e030 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
1e040 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
1e050 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
1e060 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1e070 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
1e080 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e090 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
1e0a0 20 20 3c 6c 69 3e 20 3c 62 3e 72 65 61 64 6f 6e    <li> <b>readon
1e0b0 6c 79 5f 73 68 6d 3c 2f 62 3e 3a 20 5e 54 68 65  ly_shm</b>: ^The
1e0c0 20 72 65 61 64 6f 6e 6c 79 5f 73 68 6d 20 70 61   readonly_shm pa
1e0d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1e0e0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 65 69  et to .**     ei
1e0f0 74 68 65 72 20 22 31 22 20 6f 72 20 22 30 22 2e  ther "1" or "0".
1e100 20 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22   Setting it to "
1e110 31 22 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  1" indicates tha
1e120 74 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  t if the databas
1e130 65 0a 2a 2a 20 20 20 20 20 69 73 20 69 6e 20 57  e.**     is in W
1e140 41 4c 20 6d 6f 64 65 20 61 6e 64 20 72 65 61 64  AL mode and read
1e150 2d 77 72 69 74 65 20 61 63 63 65 73 73 20 74 6f  -write access to
1e160 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
1e170 73 68 61 72 65 64 20 0a 2a 2a 20 20 20 20 20 6d  shared .**     m
1e180 65 6d 6f 72 79 20 72 65 67 69 6f 6e 20 63 61 6e  emory region can
1e190 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 64 2c  not be obtained,
1e1a0 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74   then an attempt
1e1b0 20 73 68 6f 75 6c 64 20 62 65 20 6d 61 64 65 20   should be made 
1e1c0 74 6f 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 74  to open.**     t
1e1d0 68 65 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79  he shared-memory
1e1e0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1e1f0 64 65 20 69 6e 73 74 65 61 64 2e 20 49 66 20 74  de instead. If t
1e200 68 65 72 65 20 65 78 69 73 74 20 6f 6e 65 20 6f  here exist one o
1e210 72 0a 2a 2a 20 20 20 20 20 6d 6f 72 65 20 6f 74  r.**     more ot
1e220 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6c 69  her database cli
1e230 65 6e 74 73 20 74 68 61 74 20 68 61 76 65 20 72  ents that have r
1e240 65 61 64 2d 77 72 69 74 65 20 63 6f 6e 6e 65 63  ead-write connec
1e250 74 69 6f 6e 73 20 74 6f 20 74 68 65 0a 2a 2a 20  tions to the.** 
1e260 20 20 20 20 64 61 74 61 62 61 73 65 20 73 68 61      database sha
1e270 72 65 64 2d 6d 65 6d 6f 72 79 2c 20 74 68 65 6e  red-memory, then
1e280 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 73 68 61   a read-only sha
1e290 72 65 64 2d 6d 65 6d 6f 72 79 20 63 6f 6e 6e 65  red-memory conne
1e2a0 63 74 69 6f 6e 20 77 6f 72 6b 73 20 0a 2a 2a 20  ction works .** 
1e2b0 20 20 20 20 66 69 6e 65 2e 20 48 6f 77 65 76 65      fine. Howeve
1e2c0 72 2c 20 69 66 20 74 68 65 72 65 20 65 78 69 73  r, if there exis
1e2d0 74 20 6e 6f 20 63 6c 69 65 6e 74 73 20 77 69 74  t no clients wit
1e2e0 68 20 72 65 61 64 2d 77 72 69 74 65 20 63 6f 6e  h read-write con
1e2f0 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 20 20 20  nections .**    
1e300 20 74 6f 20 74 68 65 20 73 68 61 72 65 64 2d 6d   to the shared-m
1e310 65 6d 6f 72 79 20 61 6e 64 20 74 68 65 20 6d 6f  emory and the mo
1e320 73 74 20 72 65 63 65 6e 74 20 73 75 63 68 20 63  st recent such c
1e330 72 61 73 68 65 64 20 6f 72 20 77 61 73 20 69 6e  rashed or was in
1e340 74 65 72 72 75 70 74 65 64 0a 2a 2a 20 20 20 20  terrupted.**    
1e350 20 62 79 20 61 20 70 6f 77 65 72 20 66 61 69 6c   by a power fail
1e360 75 72 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ure, then it is 
1e370 70 6f 73 73 69 62 6c 65 20 66 6f 72 20 61 20 64  possible for a d
1e380 61 74 61 62 61 73 65 20 63 6c 69 65 6e 74 20 75  atabase client u
1e390 73 69 6e 67 20 61 0a 2a 2a 20 20 20 20 20 72 65  sing a.**     re
1e3a0 61 64 2d 6f 6e 6c 79 20 63 6f 6e 6e 65 63 74 69  ad-only connecti
1e3b0 6f 6e 20 74 6f 20 72 65 74 75 72 6e 20 69 6e 63  on to return inc
1e3c0 6f 72 72 65 63 74 20 64 61 74 61 2c 20 69 6e 63  orrect data, inc
1e3d0 6f 72 72 65 63 74 6c 79 20 72 65 70 6f 72 74 20  orrectly report 
1e3e0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
1e3f0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 6f 72 20   corruption, or 
1e400 72 65 74 75 72 6e 20 61 6e 20 53 51 4c 49 54 45  return an SQLITE
1e410 5f 52 45 41 44 4f 4e 4c 59 20 65 72 72 6f 72 2e  _READONLY error.
1e420 20 4f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   Or if the.**   
1e430 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65    most recent re
1e440 61 64 2d 77 72 69 74 65 20 63 6f 6e 6e 65 63 74  ad-write connect
1e450 69 6f 6e 20 73 68 75 74 20 64 6f 77 6e 20 63 6c  ion shut down cl
1e460 65 61 6e 6c 79 2c 20 69 74 20 6d 61 79 20 6e 6f  eanly, it may no
1e470 74 20 62 65 0a 2a 2a 20 20 20 20 20 70 6f 73 73  t be.**     poss
1e480 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  ible to open the
1e490 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 69   shared-memory i
1e4a0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
1e4b0 20 61 74 20 61 6c 6c 2c 20 61 6e 64 20 53 51 4c   at all, and SQL
1e4c0 69 74 65 0a 2a 2a 20 20 20 20 20 77 69 6c 6c 20  ite.**     will 
1e4d0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 43 41  return SQLITE_CA
1e4e0 4e 54 4f 50 45 4e 2e 0a 2a 2a 20 3c 2f 75 6c 3e  NTOPEN..** </ul>
1e4f0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
1e500 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
1e510 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
1e520 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1e530 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
1e540 6e 0a 2a 2a 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n.** error..**.*
1e550 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  * URI filename e
1e560 78 61 6d 70 6c 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  xamples:.**.** <
1e570 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
1e580 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
1e590 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
1e5a0 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
1e5b0 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
1e5c0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
1e5d0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
1e5e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1e5f0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1e600 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
1e610 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
1e620 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1e630 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
1e640 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
1e650 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
1e660 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
1e670 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
1e680 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
1e690 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
1e6a0 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
1e6b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1e6c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1e6d0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
1e6e0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
1e6f0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
1e700 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
1e710 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1e720 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
1e730 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
1e740 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
1e750 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
1e760 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
1e770 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
1e780 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
1e790 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
1e7a0 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
1e7b0 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
1e7c0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
1e7d0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
1e7e0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
1e7f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
1e800 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
1e810 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
1e820 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
1e830 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
1e840 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
1e850 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
1e860 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
1e870 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
1e880 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
1e890 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
1e8a0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
1e8b0 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
1e8c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1e8d0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
1e8e0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
1e8f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1e900 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
1e910 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
1e920 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
1e930 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
1e940 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
1e950 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
1e960 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1e970 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
1e980 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
1e990 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
1e9a0 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
1e9b0 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
1e9c0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
1e9d0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
1e9e0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e  unix-nolock <td>
1e9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1ea00 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
1ea10 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
1ea20 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
1ea30 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a   "unix-nolock"..
1ea40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1ea50 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
1ea60 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
1ea70 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
1ea80 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
1ea90 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
1eaa0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
1eab0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
1eac0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
1ead0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
1eae0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
1eaf0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
1eb00 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
1eb10 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
1eb20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
1eb30 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
1eb40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
1eb50 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
1eb60 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
1eb70 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
1eb80 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
1eb90 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
1eba0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
1ebb0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
1ebc0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
1ebd0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
1ebe0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
1ebf0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
1ec00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
1ec10 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
1ec20 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
1ec30 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
1ec40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
1ec50 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
1ec60 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
1ec70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
1ec80 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
1ec90 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
1eca0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
1ecb0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
1ecc0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
1ecd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
1ece0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1ecf0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1ed00 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1ed10 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1ed20 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1ed30 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1ed40 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1ed50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1ed60 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1ed70 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1ed80 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1ed90 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1eda0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1edb0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1edc0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1edd0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1ede0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1edf0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1ee00 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1ee10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1ee20 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1ee30 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  2()..*/.int sqli
1ee40 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1ee50 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ee60 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ee70 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ee80 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ee90 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1eea0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1eeb0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1eec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1eed0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1eee0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1eef0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1ef00 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1ef10 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1ef20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ef30 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ef40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ef50 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1ef60 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ef70 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ef80 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ef90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1efa0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1efb0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1efc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1efd0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1efe0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1eff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1f000 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1f010 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1f020 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1f030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1f040 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1f050 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
1f060 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1f070 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1f080 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1f090 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1f0a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1f0b0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1f0c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1f0d0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1f0e0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1f0f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1f100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f110 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1f120 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1f130 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1f140 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1f150 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1f160 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1f170 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1f180 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1f190 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
1f1a0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1f1b0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
1f1c0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
1f1d0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1f1e0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
1f1f0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
1f200 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
1f210 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
1f220 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
1f230 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
1f240 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f250 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1f260 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f270 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1f280 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1f290 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1f2a0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1f2b0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1f2c0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1f2d0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
1f2e0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1f2f0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1f300 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1f310 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1f320 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1f330 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1f340 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1f350 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1f360 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1f370 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1f380 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1f390 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1f3a0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1f3b0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1f3c0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1f3d0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
1f3e0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1f3f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1f400 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1f410 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1f420 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1f430 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1f440 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1f450 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1f460 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1f470 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1f480 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1f490 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1f4a0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1f4b0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1f4c0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1f4d0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1f4e0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1f4f0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1f500 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1f510 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1f520 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1f530 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1f540 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1f550 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1f560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f570 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1f580 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1f590 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1f5a0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1f5b0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1f5c0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1f5d0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1f5e0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1f5f0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1f600 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1f610 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1f620 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1f630 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1f640 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1f650 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1f660 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1f670 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1f680 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1f690 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1f6a0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1f6b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1f6c0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1f6d0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1f6e0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1f6f0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1f700 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f710 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1f720 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
1f730 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1f740 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1f750 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1f760 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1f770 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1f780 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1f790 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1f7a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f7b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1f7c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1f7d0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1f7e0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1f7f0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1f800 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1f810 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1f820 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1f830 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1f840 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1f850 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1f860 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1f870 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1f880 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1f890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1f8a0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1f8b0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1f8c0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1f8d0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1f8e0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1f8f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1f900 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1f910 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1f920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1f930 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1f940 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1f950 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1f960 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1f970 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1f980 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1f990 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1f9a0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1f9b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1f9c0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1f9d0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1f9e0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1f9f0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1fa00 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1fa10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1fa20 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1fa30 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1fa40 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1fa50 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1fa60 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1fa70 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1fa80 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1fa90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1faa0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1fab0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1fac0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1fad0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1fae0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1faf0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1fb00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1fb10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1fb20 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1fb30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1fb40 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
1fb50 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
1fb60 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1fb70 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1fb80 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1fb90 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1fba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1fbb0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1fbc0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1fbd0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1fbe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fbf0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1fc00 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1fc10 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1fc20 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1fc30 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1fc40 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1fc50 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1fc60 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1fc70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1fc80 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1fc90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1fca0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1fcb0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1fcc0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
1fcd0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
1fce0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1fcf0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1fd00 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1fd10 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
1fd20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
1fd30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
1fd40 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
1fd50 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1fd60 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1fd70 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
1fd80 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
1fd90 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1fda0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
1fdb0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
1fdc0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
1fdd0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1fde0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1fdf0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1fe00 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
1fe10 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1fe20 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1fe30 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1fe40 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1fe50 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1fe60 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1fe70 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
1fe80 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1fe90 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1fea0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
1feb0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
1fec0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
1fed0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1fee0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
1fef0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
1ff00 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
1ff10 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1ff20 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
1ff30 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
1ff40 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
1ff50 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
1ff60 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
1ff70 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
1ff80 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
1ff90 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1ffa0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1ffb0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1ffc0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1ffd0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1ffe0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1fff0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
20000 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
20010 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
20020 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
20030 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
20040 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
20050 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
20060 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
20070 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
20080 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
20090 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
200a0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
200b0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
200c0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
200d0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
200e0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
200f0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
20100 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
20110 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
20120 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
20130 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
20140 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
20150 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
20160 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
20170 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
20180 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
20190 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
201a0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
201b0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
201c0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
201d0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
201e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
201f0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
20200 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
20210 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
20220 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
20230 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
20240 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
20250 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
20260 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
20270 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
20280 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
20290 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
202a0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
202b0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
202c0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
202d0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
202e0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
202f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
20300 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
20310 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
20320 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
20330 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
20340 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
20350 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
20360 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
20370 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
20380 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
20390 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
203a0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
203b0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
203c0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
203d0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
203e0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
203f0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
20400 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
20410 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
20420 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
20430 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
20440 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
20450 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
20460 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
20470 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
20480 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  dl>.** ^(<dt>SQL
20490 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
204a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
204b0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
204c0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
204d0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
204e0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
204f0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
20500 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
20510 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
20520 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
20530 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
20540 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
20550 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
20560 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20570 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
20580 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20590 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
205a0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
205b0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
205c0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
205d0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
205e0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
205f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20600 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
20610 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
20620 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
20630 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
20640 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
20650 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20660 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20670 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
20680 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
20690 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
206a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
206b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
206c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
206d0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
206e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
206f0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
20700 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
20710 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
20720 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
20740 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
20750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
20760 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
20770 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
20780 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
20790 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
207a0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
207b0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
207c0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
207d0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
207e0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
207f0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
20800 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
20810 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
20820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20830 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
20840 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
20850 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20860 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
20870 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
20880 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
20890 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
208a0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
208b0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
208c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
208d0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
208e0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
208f0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
20900 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20910 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
20920 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
20930 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20940 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
20950 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
20960 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
20970 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
20980 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
20990 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
209a0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
209b0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
209c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
209d0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
209e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
209f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
20a00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  .)^.**.** ^(<dt>
20a10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
20a20 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
20a30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20a40 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
20a50 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
20a60 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
20a70 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
20a80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
20a90 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20aa0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
20ab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
20ac0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
20ad0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
20ae0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20af0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
20b00 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
20b10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
20b20 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
20b30 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
20b40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20b50 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
20b60 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
20b70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20b80 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
20b90 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
20ba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20bb0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
20bc0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
20bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20be0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
20bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
20c00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20c10 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
20c20 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20c40 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
20c50 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
20c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20c70 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
20c80 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
20c90 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
20ca0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
20cb0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
20cc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
20cd0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
20ce0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
20cf0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
20d00 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
20d10 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
20d20 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
20d30 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
20d40 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
20d50 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
20d60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
20d70 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
20d80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20d90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
20da0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
20db0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
20dc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
20dd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20de0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
20df0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
20e00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20e10 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
20e20 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
20e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
20e40 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
20e50 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
20e60 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
20e70 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
20e80 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
20e90 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
20ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20eb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
20ec0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
20ed0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
20ee0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
20ef0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
20f00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20f10 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
20f20 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
20f30 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
20f40 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
20f50 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
20f60 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
20f70 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
20f80 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
20f90 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
20fa0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
20fb0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20fc0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
20fd0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
20fe0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
20ff0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
21000 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
21010 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
21020 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
21030 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
21040 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
21050 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
21060 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
21070 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
21080 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
21090 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
210a0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
210b0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
210c0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
210d0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
210e0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
210f0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
21100 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
21110 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
21120 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
21130 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
21140 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
21150 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
21160 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
21170 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
21180 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
21190 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
211a0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
211b0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
211c0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
211d0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
211e0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
211f0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
21200 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
21210 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
21220 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
21230 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
21240 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
21250 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
21260 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
21270 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
21280 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
21290 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
212a0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
212b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
212c0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
212d0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
212e0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
212f0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
21300 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
21310 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
21320 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
21330 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
21340 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
21350 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
21360 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
21370 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
21380 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
21390 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
213a0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
213b0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
213c0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
213d0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
213e0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
213f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
21400 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
21410 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
21420 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
21430 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
21440 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
21450 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21460 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
21470 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
21480 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
21490 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
214a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
214b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
214c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
214d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
214e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
214f0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
21500 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
21510 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
21520 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
21530 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
21540 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
21550 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
21560 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
21570 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
21580 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
21590 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
215a0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
215b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
215c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
215d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
215e0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
215f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
21600 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
21610 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
21620 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
21630 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
21640 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
21650 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
21660 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
21670 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
21680 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21690 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
216a0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
216b0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
216c0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
216d0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
216e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
216f0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
21700 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
21710 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
21720 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
21730 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
21740 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
21750 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
21760 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
21770 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
21780 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
21790 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
217a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
217b0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
217c0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
217d0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
217e0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
217f0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
21800 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
21810 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
21820 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
21830 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
21840 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
21850 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
21860 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
21870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
21880 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
21890 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
218a0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
218b0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
218c0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
218d0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
218e0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
218f0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
21900 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
21910 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
21920 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
21930 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
21940 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
21950 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
21960 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
21970 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
21980 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
21990 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
219a0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
219b0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
219c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
219d0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
219e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
219f0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
21a00 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
21a10 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
21a20 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
21a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a40 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
21a50 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
21a60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
21a70 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
21a80 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
21a90 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
21aa0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
21ab0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
21ac0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
21ad0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
21ae0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
21af0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
21b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
21b10 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
21b20 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
21b30 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
21b40 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
21b50 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
21b60 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
21b70 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
21b80 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
21b90 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65  E_STAT2] compile
21ba0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
21bb0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
21bc0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
21bd0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
21be0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
21bf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
21c00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
21c10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
21c20 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
21c30 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
21c40 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
21c50 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
21c60 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
21c70 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
21c80 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
21c90 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
21ca0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
21cb0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
21cc0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
21cd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
21ce0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
21cf0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
21d00 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
21d10 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
21d20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21d30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
21d40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
21d50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
21d60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
21d70 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
21d80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
21d90 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
21da0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
21db0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
21dc0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
21dd0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
21de0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
21df0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
21e00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
21e10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
21e20 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
21e30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
21e40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
21e50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
21e60 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
21e70 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
21e80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
21e90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
21ea0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
21eb0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
21ec0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
21ed0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
21ee0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
21ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21f00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
21f10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
21f20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
21f30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
21f40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
21f50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
21f60 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
21f70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
21f80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
21f90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
21fa0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
21fb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
21fc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
21fd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
21fe0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
21ff0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
22000 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
22010 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
22020 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
22030 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
22040 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
22050 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
22060 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
22070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
22080 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
22090 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
220a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
220b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
220c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
220d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
220e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
220f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22100 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
22110 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
22120 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
22130 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
22140 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
22150 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
22160 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
22170 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
22180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22190 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
221a0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
221b0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
221c0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
221d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
221e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
221f0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
22200 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
22210 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
22220 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
22230 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
22240 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
22250 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
22260 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
22270 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
22280 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
22290 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
222a0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
222b0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
222c0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
222d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
222e0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
222f0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
22300 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
22310 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
22320 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
22330 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
22340 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
22350 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
22360 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
22370 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
22380 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
22390 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
223a0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
223b0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
223c0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
223d0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
223e0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
223f0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
22400 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
22410 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
22420 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
22430 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
22440 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
22450 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
22460 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
22470 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
22480 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
22490 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
224a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
224b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
224c0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
224d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
224e0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
224f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
22500 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
22510 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
22520 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
22530 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
22540 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
22550 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
22560 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
22570 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
22580 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
22590 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
225a0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
225b0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
225c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
225d0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
225e0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
225f0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
22600 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
22610 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
22620 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
22630 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
22640 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
22650 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
22660 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
22670 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
22680 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
22690 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
226a0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
226b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
226c0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
226d0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
226e0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
226f0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
22700 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
22710 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
22720 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
22730 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
22740 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
22750 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
22760 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
22770 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
22780 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
22790 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
227a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
227b0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
227c0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
227d0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
227e0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
227f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
22800 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
22810 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
22820 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
22830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
22840 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
22850 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
22860 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
22870 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
22880 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
22890 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
228a0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
228b0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
228c0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
228d0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
228e0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
228f0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
22900 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
22910 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
22920 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
22930 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
22940 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
22950 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
22960 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
22970 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
22980 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
22990 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
229a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
229b0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
229c0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
229d0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
229e0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
229f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22a00 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
22a10 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
22a20 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
22a30 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
22a40 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
22a50 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
22a60 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
22a70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
22a80 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
22a90 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
22aa0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
22ab0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
22ac0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
22ad0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
22ae0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
22af0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
22b00 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
22b10 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
22b20 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
22b30 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
22b40 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
22b50 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
22b60 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
22b70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
22b80 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
22b90 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
22ba0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
22bb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
22bc0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
22bd0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
22be0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
22bf0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
22c00 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
22c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
22c20 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
22c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
22c40 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
22c50 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
22c60 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
22c70 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
22c80 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
22c90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22ca0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
22cb0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
22cc0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
22cd0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
22ce0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
22cf0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
22d00 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
22d10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
22d20 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
22d30 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
22d40 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
22d50 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
22d60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22d70 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
22d80 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
22d90 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
22da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22db0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
22dc0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
22dd0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
22de0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
22df0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
22e00 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
22e10 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
22e20 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
22e30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22e40 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
22e50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22e60 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
22e70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
22e80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22e90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
22ea0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
22eb0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
22ec0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
22ed0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
22ee0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
22ef0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
22f00 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
22f10 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
22f20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
22f30 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
22f40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22f50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
22f60 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
22f70 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
22f80 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
22f90 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
22fa0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
22fb0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
22fc0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
22fd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
22fe0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
22ff0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
23000 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
23010 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
23020 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
23030 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
23040 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
23050 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
23060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
23080 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
23090 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
230a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
230b0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
230c0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
230d0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
230e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
230f0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
23100 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
23110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
23120 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
23130 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
23140 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
23150 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
23160 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
23170 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
23180 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
23190 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
231a0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
231b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
231c0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
231d0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
231e0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
231f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
23200 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
23210 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
23220 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
23230 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
23240 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23250 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
23260 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
23270 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
23280 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
23290 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
232a0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
232b0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
232c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
232d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
232e0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
232f0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
23300 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
23310 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
23320 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
23330 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
23340 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
23350 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
23360 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
23370 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
23380 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
23390 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
233a0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
233b0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
233c0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
233d0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
233e0 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
233f0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
23400 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
23410 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
23420 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
23430 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
23440 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
23450 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
23460 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
23470 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
23480 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
23490 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
234a0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
234b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
234c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
234d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
234e0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
234f0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
23500 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23510 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
23520 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
23530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23540 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
23550 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
23560 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
23570 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
23580 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
23590 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
235a0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
235b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
235c0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
235d0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
235e0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
235f0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
23600 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
23610 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
23620 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
23630 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
23640 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
23650 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
23660 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
23670 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
23680 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
23690 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
236a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
236b0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
236c0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
236d0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
236e0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
236f0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
23700 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
23710 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
23720 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
23730 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
23740 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
23750 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
23760 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23770 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
23780 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
23790 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
237a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
237b0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
237c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
237d0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
237e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
237f0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
23800 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
23810 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
23820 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
23830 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
23840 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
23850 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
23860 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
23870 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
23880 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
23890 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
238a0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
238b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
238c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
238d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
238e0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
238f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
23900 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
23910 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
23920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
23930 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
23940 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
23950 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
23960 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
23970 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
23980 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
23990 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
239a0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
239b0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
239c0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
239d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
239e0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
239f0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
23a00 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
23a10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
23a20 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
23a30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
23a40 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
23a50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
23a60 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
23a70 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
23a80 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
23a90 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
23aa0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
23ab0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
23ac0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
23ad0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
23ae0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
23af0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
23b00 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
23b10 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
23b20 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
23b30 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
23b40 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
23b50 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
23b60 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
23b70 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
23b80 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
23b90 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
23ba0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
23bb0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
23bc0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
23bd0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
23be0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23bf0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
23c00 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
23c10 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
23c20 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
23c30 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
23c40 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
23c50 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
23c60 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
23c70 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
23c80 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
23c90 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
23ca0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
23cb0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
23cc0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
23cd0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
23ce0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
23cf0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
23d00 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
23d10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
23d20 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
23d30 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
23d40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
23d50 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
23d60 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
23d70 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
23d80 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
23d90 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
23da0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23db0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
23dc0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
23dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
23de0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
23df0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
23e00 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
23e10 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
23e20 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
23e30 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
23e40 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
23e50 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
23e60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
23e70 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
23e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
23e90 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
23ea0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
23eb0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
23ec0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
23ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23ee0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
23ef0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
23f00 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
23f10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
23f20 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
23f30 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
23f40 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
23f50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
23f60 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
23f70 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
23f80 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
23f90 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
23fa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23fb0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
23fc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
23fd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
23fe0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
23ff0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
24000 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
24010 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
24020 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
24030 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
24040 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
24050 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
24060 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
24070 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
24080 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
24090 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
240a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
240b0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
240c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
240d0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
240e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
240f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
24100 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24110 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
24120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24130 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
24140 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
24150 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
24160 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
24170 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
24180 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
24190 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
241a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
241b0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
241c0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
241d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
241e0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
241f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
24200 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
24210 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
24220 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
24230 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
24240 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
24250 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
24260 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
24270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
24280 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
24290 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
242a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
242b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
242c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
242d0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
242e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
242f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
24300 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
24310 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
24320 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
24330 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
24340 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
24350 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
24360 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
24370 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
24380 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
24390 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
243a0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
243b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
243c0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
243d0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
243e0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
243f0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
24400 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
24410 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
24420 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
24430 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
24440 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
24450 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
24460 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
24470 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
24480 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
24490 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
244a0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
244b0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
244c0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
244d0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
244e0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
244f0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
24500 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
24510 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
24520 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
24530 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
24540 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
24550 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
24560 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
24570 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
24580 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
24590 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
245a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
245b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
245c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
245d0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
245e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
245f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
24600 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
24610 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24620 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
24630 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
24640 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
24650 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
24660 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
24670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24680 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
24690 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
246a0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
246b0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
246c0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
246d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
246e0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
246f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
24700 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
24710 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
24720 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
24730 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
24740 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
24750 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
24760 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
24770 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
24780 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
24790 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
247a0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
247b0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
247c0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
247d0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
247e0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
247f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
24800 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
24810 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
24820 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
24830 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
24840 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
24850 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
24860 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
24870 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
24880 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
24890 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
248a0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
248b0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
248c0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
248d0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
248e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
248f0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
24900 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
24910 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
24920 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
24930 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
24940 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
24950 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
24960 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
24970 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
24980 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
24990 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
249a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
249b0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
249c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
249d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
249e0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
249f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
24a00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
24a10 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
24a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24a30 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
24a40 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
24a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24a60 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
24a70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
24a80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24a90 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
24aa0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
24ab0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
24ac0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
24ad0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
24ae0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
24af0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
24b00 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
24b10 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
24b20 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
24b30 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
24b40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24b50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
24b60 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
24b70 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
24b80 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
24b90 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
24ba0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
24bb0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
24bc0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
24bd0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
24be0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
24bf0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
24c00 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
24c10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24c20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
24c30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
24c40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
24c50 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
24c60 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
24c70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24c80 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
24c90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
24ca0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
24cb0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
24cc0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24cd0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
24ce0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
24cf0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
24d00 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
24d10 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
24d20 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
24d30 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
24d40 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
24d50 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
24d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24d70 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
24d80 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
24d90 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
24da0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
24db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24dc0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
24dd0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
24de0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
24df0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
24e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
24e10 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
24e20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
24e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
24e40 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
24e50 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
24e60 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
24e70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
24e80 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
24e90 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
24ea0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
24ec0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
24ed0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
24ee0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
24ef0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
24f00 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
24f10 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
24f20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
24f30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24f40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
24f50 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
24f60 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
24f70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
24f80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24f90 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
24fa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
24fb0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
24fc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
24fd0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
24fe0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
24ff0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
25000 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
25010 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
25020 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
25030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
25040 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
25050 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
25060 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
25070 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
25080 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
25090 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
250a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
250b0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
250c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
250d0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
250e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
250f0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
25100 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
25110 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
25120 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
25130 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
25140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25150 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
25160 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
25170 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
25180 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
25190 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
251a0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
251b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
251c0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
251d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
251e0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
251f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25200 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
25210 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
25220 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
25230 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
25240 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
25250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25260 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
25270 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
25280 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
25290 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
252a0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
252b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
252c0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
252d0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
252e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
252f0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
25300 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
25310 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
25320 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
25330 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
25340 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
25350 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
25360 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
25370 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
25380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
25390 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
253a0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
253b0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
253c0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
253d0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
253e0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
253f0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
25400 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
25410 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
25420 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
25430 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
25440 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
25450 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
25460 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
25470 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
25480 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25490 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
254a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
254b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
254c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
254d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
254e0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
254f0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
25500 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
25510 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
25520 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
25530 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
25540 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
25550 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
25560 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
25570 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
25580 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
25590 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
255a0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
255b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
255c0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
255d0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
255e0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
255f0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
25600 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
25610 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
25620 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
25630 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
25640 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
25650 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
25660 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
25670 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
25680 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
25690 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
256a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
256b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
256c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
256d0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
256e0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
256f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
25700 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
25710 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
25720 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
25730 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
25740 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
25750 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
25760 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
25770 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25780 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
25790 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
257a0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
257b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
257c0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
257d0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
257e0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
257f0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
25800 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
25810 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
25820 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
25830 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
25840 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
25850 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
25860 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
25870 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
25880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25890 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
258a0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
258b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
258c0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
258d0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
258e0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
258f0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
25900 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
25910 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
25920 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
25930 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
25940 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
25950 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
25960 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
25970 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
25980 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
25990 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
259a0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
259b0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
259c0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
259d0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
259e0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
259f0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
25a00 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
25a10 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
25a20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
25a30 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
25a40 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
25a50 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
25a60 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
25a70 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
25a80 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
25a90 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
25aa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
25ab0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
25ac0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
25ad0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
25ae0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
25af0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
25b00 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
25b10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
25b20 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
25b30 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
25b40 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
25b50 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
25b60 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
25b70 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
25b80 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
25b90 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
25ba0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
25bb0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
25bc0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
25bd0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
25be0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
25bf0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
25c00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
25c10 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
25c20 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
25c30 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
25c40 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
25c50 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
25c60 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
25c70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
25c80 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
25c90 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
25ca0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
25cb0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25cc0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
25cd0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
25ce0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
25cf0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
25d00 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
25d10 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
25d20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
25d30 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
25d40 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
25d50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
25d70 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
25d80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25d90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25da0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25db0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
25dc0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25dd0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25de0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
25df0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
25e00 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
25e10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
25e20 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
25e30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25e40 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
25e60 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
25e70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25e80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25e90 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
25ea0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
25eb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
25ec0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
25ed0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
25ee0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
25ef0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
25f00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
25f10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25f20 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
25f30 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
25f40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
25f50 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
25f60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
25f70 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
25f80 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
25f90 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
25fa0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
25fb0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
25fc0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
25fd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
25fe0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
25ff0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
26000 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
26010 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
26020 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
26030 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
26040 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
26050 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
26060 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
26070 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
26080 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
26090 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
260a0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
260b0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
260c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
260d0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
260e0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
260f0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
26100 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
26110 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
26120 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
26130 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
26140 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
26150 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
26160 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
26170 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
26180 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
26190 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
261a0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
261b0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
261c0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
261d0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
261e0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
261f0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
26200 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
26210 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
26220 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
26230 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
26240 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
26250 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
26260 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
26270 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
26280 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
26290 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
262a0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
262b0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
262c0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
262d0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
262e0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
262f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
26300 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
26310 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
26320 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
26330 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
26340 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
26350 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
26360 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
26370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26380 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
263a0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
263b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
263c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
263d0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
263e0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
263f0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
26400 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
26410 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
26420 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
26430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26440 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26450 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
26460 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
26470 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
26480 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
26490 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
264a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
264b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
264c0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
264d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
264e0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
264f0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
26500 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
26510 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
26520 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
26530 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
26540 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
26550 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
26560 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
26570 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
26580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
26590 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
265a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
265b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
265c0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
265d0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
265e0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
265f0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
26600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26610 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
26620 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
26630 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
26640 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
26650 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
26660 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
26670 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
26680 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
26690 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
266a0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
266b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
266c0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
266d0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
266e0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
266f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
26700 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
26710 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
26720 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
26730 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
26740 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
26750 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
26760 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
26770 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
26780 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
26790 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
267a0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
267b0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
267c0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
267d0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
267e0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
267f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
26800 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
26810 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
26820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
26830 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
26840 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
26850 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
26860 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
26870 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
26880 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
26890 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
268a0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
268b0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
268c0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
268d0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
268e0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
268f0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
26900 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
26910 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
26920 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
26930 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
26940 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
26950 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
26960 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
26970 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
26980 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
26990 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
269a0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
269b0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
269c0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
269d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
269e0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
269f0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
26a00 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
26a10 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
26a20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
26a30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
26a40 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
26a50 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
26a60 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
26a70 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
26a80 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
26a90 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
26aa0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
26ab0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
26ac0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
26ad0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
26ae0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
26af0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
26b00 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
26b10 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
26b20 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
26b30 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
26b40 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
26b50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
26b60 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
26b70 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
26b80 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
26b90 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
26ba0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
26bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
26bc0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
26bd0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
26be0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
26bf0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
26c00 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
26c10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
26c20 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
26c30 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26c40 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
26c50 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
26c60 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
26c70 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
26c80 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
26c90 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
26ca0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
26cb0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
26cc0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
26cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26ce0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
26cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26d00 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
26d10 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
26d20 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
26d30 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
26d40 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
26d50 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
26d60 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
26d70 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
26d80 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
26d90 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
26da0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
26db0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
26dc0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
26dd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26de0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
26df0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
26e00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
26e10 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
26e20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
26e30 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
26e40 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
26e50 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
26e60 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
26e70 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
26e80 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
26e90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26ea0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
26eb0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
26ec0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
26ed0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
26ee0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
26ef0 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
26f00 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
26f10 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
26f20 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
26f30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
26f40 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
26f50 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
26f60 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
26f70 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
26f80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
26f90 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
26fa0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
26fb0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
26fc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
26fd0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
26fe0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
26ff0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
27000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27010 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
27020 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
27030 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
27040 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
27050 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
27060 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
27070 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
27080 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
27090 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
270a0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
270b0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
270c0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
270d0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
270e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
270f0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
27100 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
27110 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
27120 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
27130 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
27140 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
27150 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
27160 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
27170 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
27180 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
27190 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
271a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
271b0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
271c0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
271d0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
271e0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
271f0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
27200 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
27210 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
27220 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
27230 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
27240 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
27250 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
27260 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
27270 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
27280 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
27290 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
272a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
272b0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
272c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
272d0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
272e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
272f0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
27300 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
27310 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
27320 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
27330 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
27340 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
27350 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
27360 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
27370 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
27380 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
27390 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
273a0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
273b0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
273c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
273d0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
273e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
273f0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
27400 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27410 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
27420 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
27430 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
27440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
27450 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
27460 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
27470 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
27480 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
27490 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
274a0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
274b0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
274c0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
274d0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
274e0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
274f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
27500 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
27510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
27520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
27530 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
27540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27550 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
27560 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27570 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
27580 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
27590 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
275a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
275b0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
275c0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
275d0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
275e0 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
275f0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
27600 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
27610 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
27620 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
27630 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
27640 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
27650 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
27660 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
27670 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
27680 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
27690 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
276a0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
276b0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
276c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
276d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
276e0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
276f0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
27700 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
27710 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27720 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27730 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
27740 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
27750 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
27760 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
27770 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
27780 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
27790 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
277a0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
277b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
277c0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
277d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
277e0 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
277f0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
27800 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
27810 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
27820 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
27830 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
27840 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
27850 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
27860 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
27870 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27880 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
27890 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
278a0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
278b0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
278c0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
278d0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
278e0 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
278f0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
27900 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
27910 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
27920 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
27930 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
27940 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
27950 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
27960 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
27970 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
27980 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
27990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
279a0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
279b0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
279c0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
279d0 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
279e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
279f0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
27a00 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
27a10 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
27a20 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
27a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27a40 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
27a50 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
27a60 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
27a70 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
27a80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
27a90 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
27aa0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
27ab0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
27ac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
27ad0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
27ae0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
27af0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
27b00 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
27b10 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
27b20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
27b30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
27b40 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
27b50 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
27b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
27b70 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
27b80 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
27b90 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
27ba0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
27bb0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
27bc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27bd0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
27be0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
27bf0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
27c00 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
27c10 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
27c20 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
27c30 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
27c40 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
27c50 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
27c60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
27c70 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
27c80 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
27c90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
27ca0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
27cb0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
27cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
27cd0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
27ce0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
27cf0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
27d00 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
27d10 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
27d20 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
27d30 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
27d40 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
27d50 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
27d60 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
27d70 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
27d80 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
27d90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
27da0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
27db0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
27dc0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
27dd0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
27de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
27df0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
27e00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
27e10 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
27e20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
27e30 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
27e40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
27e50 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
27e60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
27e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
27e80 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
27e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27ea0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
27eb0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
27ec0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
27ed0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
27ee0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27ef0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
27f00 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
27f10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
27f20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27f30 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
27f40 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
27f50 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
27f60 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
27f70 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
27f80 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
27f90 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
27fa0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
27fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27fc0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
27fd0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
27fe0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
27ff0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
28000 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
28010 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
28020 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
28030 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
28040 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
28050 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
28060 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
28070 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
28080 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
28090 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
280a0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
280b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
280c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
280d0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
280e0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
280f0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
28100 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
28110 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
28120 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
28130 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
28140 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
28150 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
28160 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
28170 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
28180 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
28190 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
281a0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
281b0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
281c0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
281d0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
281e0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
281f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
28200 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
28210 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
28220 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
28230 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
28240 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
28250 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28260 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
28270 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28280 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
28290 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
282a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
282b0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
282c0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
282d0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
282e0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
282f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
28300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
28310 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
28320 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
28330 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28340 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
28350 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
28360 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
28370 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
28380 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
28390 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
283a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
283b0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
283c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
283d0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
283e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
283f0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
28400 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
28410 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
28420 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
28430 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
28440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28450 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
28460 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28470 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28480 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
28490 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
284a0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
284b0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
284c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
284d0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
284e0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
284f0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
28500 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
28510 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
28520 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28530 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
28540 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
28550 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
28560 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
28570 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
28580 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
28590 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
285a0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
285b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
285c0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
285d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
285e0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
285f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
28600 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
28610 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
28620 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
28630 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
28640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28650 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
28660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28670 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
28680 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
28690 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
286a0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
286b0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
286c0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
286d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
286e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
286f0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
28700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28710 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
28720 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
28730 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
28740 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
28750 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
28760 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
28770 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
28780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28790 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
287a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
287b0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
287c0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
287d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
287e0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
287f0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
28800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
28810 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
28820 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
28830 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
28840 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
28850 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
28860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
28870 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
28880 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28890 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
288a0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
288b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
288c0 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
288d0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
288e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
288f0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
28900 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
28910 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
28920 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28930 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28940 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
28950 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28960 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
28970 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
28980 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
28990 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
289a0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
289b0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
289c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
289d0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
289e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
289f0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
28a00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
28a10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
28a20 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
28a30 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
28a40 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
28a50 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
28a60 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
28a70 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
28a80 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
28a90 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
28aa0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
28ab0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
28ac0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
28ad0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
28ae0 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
28af0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
28b00 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
28b10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
28b20 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
28b30 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
28b40 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
28b50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
28b60 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
28b70 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
28b80 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
28b90 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
28ba0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
28bb0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
28bc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
28bd0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
28be0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
28bf0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
28c00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
28c10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
28c20 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
28c30 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
28c40 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
28c50 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
28c60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
28c70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
28c80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
28c90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
28ca0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
28cb0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
28cc0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
28cd0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
28ce0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
28cf0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
28d00 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
28d10 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
28d20 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
28d30 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
28d40 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
28d50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28d60 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
28d70 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
28d80 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
28d90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
28da0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
28db0 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
28dc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
28dd0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
28de0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
28df0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
28e00 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
28e10 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
28e20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
28e30 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
28e40 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
28e50 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
28e60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
28e70 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
28e80 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
28e90 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
28ea0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
28eb0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
28ec0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
28ed0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
28ee0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
28ef0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
28f00 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
28f10 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
28f20 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
28f30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
28f40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
28f50 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
28f60 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
28f70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
28f80 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
28f90 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
28fa0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
28fb0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
28fc0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
28fd0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
28fe0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
28ff0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
29000 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
29010 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
29020 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
29030 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
29040 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
29050 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29060 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
29070 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
29080 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
29090 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
290a0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
290b0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
290c0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
290d0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
290e0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
290f0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
29100 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
29110 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
29120 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
29130 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
29140 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
29150 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
29160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29170 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
29180 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
29190 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
291a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
291b0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
291c0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
291d0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
291e0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
291f0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
29200 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
29210 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
29220 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
29230 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
29240 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
29250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29260 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
29270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29280 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
29290 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
292a0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
292b0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
292c0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
292d0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
292e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
292f0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
29300 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
29310 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
29320 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
29330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29340 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
29350 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
29360 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
29370 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
29380 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
29390 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
293a0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
293b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
293c0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
293d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
293e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
293f0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
29400 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
29410 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
29420 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
29430 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
29440 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
29450 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
29460 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
29470 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
29480 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
29490 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
294a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
294b0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
294c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
294d0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
294e0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
294f0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
29500 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
29510 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
29520 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
29530 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
29540 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
29550 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
29560 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
29570 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
29580 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
29590 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
295a0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
295b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
295c0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
295d0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
295e0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
295f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
29600 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
29610 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
29620 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
29630 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
29640 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
29650 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
29660 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
29670 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
29680 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
29690 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
296a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
296b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
296c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
296d0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
296e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
296f0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
29700 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
29710 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
29720 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
29730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29740 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
29750 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
29760 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
29770 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
29780 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
29790 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
297a0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
297b0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
297c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
297d0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
297e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
297f0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
29800 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
29810 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
29820 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
29830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29840 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
29850 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
29860 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
29870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29880 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
29890 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
298a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
298b0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
298c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
298d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
298e0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
298f0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
29900 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
29910 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
29920 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
29930 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
29940 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
29950 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
29960 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
29970 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
29980 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
29990 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
299a0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
299b0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
299c0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
299d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
299e0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
299f0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
29a00 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
29a10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
29a20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
29a30 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
29a40 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
29a50 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
29a60 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
29a70 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
29a80 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
29a90 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
29aa0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
29ab0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
29ac0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
29ad0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
29ae0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
29af0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
29b00 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
29b10 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
29b20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
29b30 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
29b40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
29b50 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
29b60 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
29b70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
29b80 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
29b90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29ba0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
29bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29bc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29bd0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
29be0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
29bf0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
29c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29c20 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
29c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29c40 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
29c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29c60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
29c70 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
29c80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29c90 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
29ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
29cb0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
29cc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
29cd0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
29ce0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
29cf0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
29d00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29d10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
29d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29d30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
29d40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29d50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29d60 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
29d70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
29d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
29d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
29da0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
29db0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
29dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29dd0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
29de0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
29df0 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
29e00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29e10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
29e20 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
29e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29e40 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
29e50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
29e60 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
29e70 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
29e80 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f  ered no errors o
29e90 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  r.** or if the s
29ea0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
29eb0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
29ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
29ed0 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
29ee0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
29ef0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
29f00 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
29f10 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
29f20 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
29f30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29f40 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
29f50 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
29f60 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
29f70 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
29f80 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
29f90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29fa0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
29fb0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
29fc0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
29fd0 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
29fe0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
29ff0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2a000 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2a010 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2a020 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2a030 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2a040 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2a050 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2a060 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2a070 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2a080 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2a090 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2a0a0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2a0b0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2a0c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2a0d0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2a0e0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2a0f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2a100 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2a110 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2a120 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2a130 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2a140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2a150 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2a160 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2a170 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2a180 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2a190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2a1a0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2a1b0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2a1c0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2a1d0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2a1e0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2a1f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2a200 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2a210 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2a220 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2a230 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2a240 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2a250 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2a260 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2a270 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2a280 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2a290 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2a2a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a2b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2a2c0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2a2d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2a2e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a2f0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2a300 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2a310 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2a320 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2a330 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2a340 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2a350 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2a360 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2a370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2a380 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2a390 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2a3a0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2a3b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2a3c0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2a3d0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2a3e0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2a3f0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2a400 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2a410 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2a420 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2a430 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2a440 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2a450 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2a460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a470 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2a480 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2a490 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2a4a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2a4b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a4c0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2a4d0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2a4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a4f0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2a500 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2a510 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2a520 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2a530 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2a540 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2a550 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2a560 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2a570 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2a580 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2a590 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2a5a0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a5b0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a5c0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2a5d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a5e0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2a5f0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2a600 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2a610 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2a620 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2a630 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2a640 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a650 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2a660 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2a670 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2a680 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2a690 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2a6a0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2a6b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2a6c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2a6d0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2a6e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2a6f0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2a700 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2a710 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2a720 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2a730 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2a740 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2a750 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2a760 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a770 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2a780 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2a790 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a7a0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2a7b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2a7c0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2a7d0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2a7e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2a7f0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2a800 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2a810 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2a820 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2a830 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2a840 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2a850 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2a860 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2a870 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2a880 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2a890 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2a8a0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2a8b0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2a8c0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2a8d0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2a8e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2a8f0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2a900 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2a910 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2a920 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2a930 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2a940 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2a950 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2a960 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2a970 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2a980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a990 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2a9a0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2a9b0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2a9c0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2a9d0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2a9e0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2a9f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2aa00 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2aa10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2aa20 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2aa30 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2aa40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2aa50 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2aa60 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2aa70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2aa80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2aa90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2aaa0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2aab0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2aac0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2aad0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2aae0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2aaf0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2ab00 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2ab10 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2ab20 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2ab30 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2ab40 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2ab50 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2ab60 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2ab70 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2ab80 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2ab90 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2aba0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2abb0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2abc0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2abd0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2abe0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2abf0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2ac00 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2ac10 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2ac20 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2ac30 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2ac40 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2ac50 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2ac60 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2ac70 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2ac80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2ac90 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2aca0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2acb0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2acc0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2acd0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2ace0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2acf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2ad00 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2ad10 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2ad20 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2ad30 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2ad40 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2ad50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2ad60 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2ad70 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2ad80 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2ad90 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2ada0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2adb0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2adc0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2add0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2ade0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2adf0 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2ae00 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2ae10 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2ae20 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2ae30 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2ae40 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2ae50 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2ae60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2ae70 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2ae80 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2ae90 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2aea0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2aeb0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2aec0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2aed0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2aee0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2aef0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2af00 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2af10 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2af20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2af30 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2af40 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2af50 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2af60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2af70 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2af80 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2af90 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2afa0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2afb0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2afc0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2afd0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2afe0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2aff0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2b000 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b010 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2b020 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2b030 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2b040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2b050 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2b060 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2b070 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2b080 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2b090 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2b0a0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2b0b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b0c0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2b0d0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2b0e0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2b0f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b100 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2b110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2b120 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2b130 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2b140 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2b150 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2b160 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2b170 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2b180 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2b190 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b1a0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b1b0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2b1c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b1d0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2b1e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2b1f0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2b200 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2b210 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2b220 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2b230 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2b240 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2b250 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2b260 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2b270 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b280 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2b290 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2b2a0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2b2b0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2b2c0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2b2d0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2b2e0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2b2f0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2b300 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2b310 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2b320 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2b330 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2b340 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2b350 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b360 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2b370 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2b380 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2b390 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2b3a0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2b3b0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2b3c0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2b3d0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2b3e0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2b3f0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2b400 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2b410 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2b420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2b430 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2b440 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2b450 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2b460 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2b470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b480 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2b490 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2b4a0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2b4b0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2b4c0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2b4d0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2b4e0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2b4f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2b500 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2b510 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2b520 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2b530 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2b540 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b550 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b560 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2b570 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2b580 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2b590 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2b5a0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2b5b0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2b5c0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2b5d0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2b5e0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2b5f0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2b600 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2b610 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2b620 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2b630 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2b640 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2b650 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2b660 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2b670 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2b680 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2b690 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2b6a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2b6b0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2b6c0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2b6d0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2b6e0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2b6f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2b700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2b710 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2b720 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2b730 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2b740 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2b750 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2b760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2b770 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2b780 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2b790 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2b7a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2b7b0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2b7c0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2b7d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2b7e0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2b7f0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2b800 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2b810 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2b820 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2b830 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2b840 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2b850 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2b860 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2b870 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2b880 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2b890 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2b8a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b8b0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2b8c0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2b8d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b8e0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2b8f0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2b900 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2b910 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2b920 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2b930 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2b940 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b950 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2b960 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2b970 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2b980 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2b990 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2b9a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
2b9b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b9c0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2b9d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2b9e0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2b9f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2ba00 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2ba10 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2ba20 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2ba30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2ba40 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2ba50 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2ba60 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2ba70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2ba80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2ba90 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2baa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2bab0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2bac0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2bad0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2bae0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2baf0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2bb00 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2bb10 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2bb20 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2bb30 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2bb40 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2bb50 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2bb60 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2bb70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2bb80 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2bb90 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2bba0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2bbb0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2bbc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bbd0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
2bbe0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2bbf0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2bc00 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2bc10 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2bc20 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2bc30 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2bc40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2bc50 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2bc60 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2bc70 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2bc80 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2bc90 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2bca0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2bcb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2bcc0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2bcd0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
2bce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2bcf0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
2bd00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2bd10 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2bd20 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2bd30 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2bd40 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2bd50 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2bd60 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2bd70 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2bd80 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2bd90 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2bda0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2bdb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2bdc0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2bdd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2bde0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2bdf0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2be00 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2be10 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2be20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2be30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2be40 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2be50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2be60 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2be70 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2be80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2be90 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2bea0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
2beb0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
2bec0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
2bed0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2bee0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
2bef0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
2bf00 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
2bf10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2bf20 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
2bf30 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
2bf40 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2bf50 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
2bf60 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
2bf70 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2bf80 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
2bf90 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
2bfa0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
2bfb0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
2bfc0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
2bfd0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
2bfe0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
2bff0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
2c000 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
2c010 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
2c020 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
2c030 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
2c040 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2c050 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2c060 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2c070 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
2c080 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2c090 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2c0a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2c0b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2c0c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
2c0d0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
2c0e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
2c0f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2c100 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2c110 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2c120 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2c130 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2c140 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
2c150 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2c160 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2c170 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2c180 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2c190 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2c1a0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2c1b0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2c1c0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
2c1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c1e0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2c1f0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2c200 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
2c210 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2c220 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2c230 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2c240 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2c250 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2c260 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2c270 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2c280 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2c290 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2c2a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2c2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2c2c0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2c2d0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2c2e0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2c2f0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2c300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2c310 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2c320 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2c330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2c340 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2c350 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2c360 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2c370 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2c380 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
2c390 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2c3a0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2c3b0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2c3c0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2c3d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c3e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2c3f0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2c400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c410 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2c420 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2c430 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2c440 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c450 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2c460 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2c470 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2c480 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2c490 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2c4a0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2c4b0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2c4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c4d0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2c4e0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2c4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2c500 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2c510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2c520 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2c530 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2c540 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
2c550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2c560 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2c570 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2c580 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2c590 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2c5a0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2c5b0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2c5c0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2c5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c5e0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2c5f0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2c600 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2c610 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2c620 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2c630 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2c640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c650 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2c660 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2c670 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2c680 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2c690 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2c6a0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
2c6b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c6c0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2c6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c6e0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2c6f0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2c700 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2c710 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2c720 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2c730 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2c740 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
2c750 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2c760 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2c770 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2c780 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2c790 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2c7a0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2c7b0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2c7c0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2c7d0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2c7e0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2c7f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2c800 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2c810 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2c820 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2c830 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2c840 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2c850 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2c860 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2c870 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2c880 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2c890 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2c8a0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2c8b0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2c8c0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2c8d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2c8e0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2c8f0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2c900 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2c910 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2c920 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2c930 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2c940 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2c950 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2c960 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2c970 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2c980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c990 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2c9a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2c9b0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2c9c0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2c9d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2c9e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2c9f0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2ca00 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2ca10 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2ca20 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2ca30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2ca40 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2ca50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ca60 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2ca70 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2ca80 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2ca90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2caa0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2cab0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2cac0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
2cad0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cae0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2caf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cb00 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2cb10 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2cb20 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2cb30 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2cb40 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2cb50 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2cb60 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2cb70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cb80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2cb90 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2cba0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2cbb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2cbc0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2cbd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2cbe0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2cbf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cc00 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2cc10 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2cc20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cc30 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2cc40 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2cc50 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2cc60 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2cc70 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2cc80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cc90 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2cca0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ccb0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2ccc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2ccd0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2cce0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2ccf0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2cd00 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2cd10 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2cd20 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2cd30 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2cd40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2cd50 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2cd60 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2cd70 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2cd80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2cd90 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2cda0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2cdb0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2cdc0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2cdd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2cde0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2cdf0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2ce00 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2ce10 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2ce20 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2ce30 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2ce40 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2ce50 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2ce60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2ce70 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2ce80 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2ce90 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2cea0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2ceb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cec0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2ced0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2cee0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2cef0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2cf00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2cf10 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2cf20 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2cf30 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2cf40 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2cf50 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2cf60 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2cf70 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2cf80 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2cf90 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2cfa0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2cfb0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2cfc0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2cfd0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2cfe0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2cff0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2d000 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2d010 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2d020 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2d030 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2d040 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2d050 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2d060 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2d070 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d080 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2d090 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2d0a0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2d0b0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2d0c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d0d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d0e0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2d0f0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2d100 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2d110 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2d120 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2d130 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2d140 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2d150 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2d160 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2d170 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2d180 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d190 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2d1a0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2d1b0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2d1c0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2d1d0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2d1e0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2d1f0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2d200 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2d210 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d220 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2d230 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2d240 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2d250 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2d260 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2d270 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2d280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2d290 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2d2a0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2d2b0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2d2c0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2d2d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2d2e0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2d2f0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2d300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2d310 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2d320 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2d330 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2d340 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2d350 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2d360 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2d370 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2d380 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2d390 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2d3a0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2d3b0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2d3c0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2d3d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2d3e0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2d3f0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2d400 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2d410 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2d420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2d430 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2d440 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2d450 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2d460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d470 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2d480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2d490 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2d4a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2d4b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2d4c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2d4d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2d4e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2d4f0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2d500 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2d510 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2d520 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2d530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d540 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2d550 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d560 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2d570 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2d580 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2d590 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2d5a0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2d5b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2d5c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2d5d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2d5e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2d5f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2d600 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d610 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2d620 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2d630 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2d640 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2d650 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2d660 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2d670 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2d680 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
2d690 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2d6a0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2d6b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d6c0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2d6d0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2d6e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d6f0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2d700 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2d710 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2d720 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2d730 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2d740 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d750 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2d760 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2d770 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2d780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2d790 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2d7a0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2d7b0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2d7c0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2d7d0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2d7e0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2d7f0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2d800 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
2d810 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
2d820 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
2d830 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
2d840 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
2d850 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
2d860 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
2d870 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
2d880 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
2d890 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
2d8a0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
2d8b0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
2d8c0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
2d8d0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
2d8e0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
2d8f0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
2d900 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
2d910 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2d920 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2d930 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2d940 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2d950 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2d960 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2d970 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2d980 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2d990 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2d9a0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2d9b0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2d9c0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2d9d0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2d9e0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2d9f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2da00 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2da10 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2da20 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2da30 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2da40 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2da50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2da60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2da70 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2da80 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2da90 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2daa0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2dab0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2dac0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2dad0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2dae0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2daf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2db00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2db10 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
2db20 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
2db30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2db40 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
2db50 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
2db60 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
2db70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2db80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2db90 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
2dba0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
2dbb0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
2dbc0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
2dbd0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
2dbe0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
2dbf0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
2dc00 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
2dc10 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
2dc20 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2dc30 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
2dc40 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2dc50 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
2dc60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2dc70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc80 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2dc90 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2dca0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
2dcb0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
2dcc0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
2dcd0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
2dce0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2dcf0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2dd00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dd10 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2dd20 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2dd30 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2dd40 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2dd50 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2dd60 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2dd70 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2dd80 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
2dd90 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2dda0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2ddb0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2ddc0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
2ddd0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
2dde0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
2ddf0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
2de00 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
2de10 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
2de20 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
2de30 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2de40 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2de50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
2de60 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
2de70 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
2de80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
2de90 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
2dea0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
2deb0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
2dec0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
2ded0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2dee0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2def0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
2df00 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
2df10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
2df20 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
2df30 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
2df40 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
2df50 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
2df60 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
2df70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
2df80 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
2df90 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
2dfa0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
2dfb0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
2dfc0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
2dfd0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
2dfe0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
2dff0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
2e000 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e010 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2e020 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2e030 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2e040 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2e050 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2e060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
2e070 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e080 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e090 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2e0a0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
2e0b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2e0c0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
2e0d0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
2e0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e0f0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
2e100 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
2e110 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
2e120 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
2e130 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
2e140 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2e150 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2e160 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2e170 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2e180 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2e190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2e1a0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
2e1b0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
2e1c0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
2e1d0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
2e1e0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2e1f0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
2e200 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
2e210 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
2e220 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
2e230 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
2e240 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
2e250 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
2e260 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
2e270 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
2e280 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
2e290 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
2e2a0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
2e2b0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
2e2c0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2e2d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
2e2e0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
2e2f0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
2e300 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
2e310 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
2e320 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
2e330 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
2e340 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
2e350 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
2e360 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
2e370 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
2e380 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
2e390 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2e3a0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
2e3b0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2e3c0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
2e3d0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
2e3e0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
2e3f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
2e400 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
2e410 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
2e420 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
2e430 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
2e440 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2e450 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
2e460 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
2e470 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
2e480 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
2e490 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2e4a0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e4c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2e4d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e4e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2e4f0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
2e500 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2e510 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2e520 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
2e530 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
2e540 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
2e550 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
2e560 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
2e570 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
2e580 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
2e590 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e5a0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
2e5b0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
2e5c0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
2e5d0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
2e5e0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2e5f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e600 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2e610 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2e620 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2e630 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2e640 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e650 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2e660 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2e670 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2e680 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2e690 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2e6a0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2e6b0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2e6c0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2e6d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2e6e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2e6f0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
2e700 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
2e710 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2e720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e730 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2e740 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
2e750 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
2e760 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
2e770 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
2e780 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
2e790 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
2e7a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
2e7b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2e7c0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2e7d0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2e7e0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2e7f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e800 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2e810 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2e820 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2e830 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2e840 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2e860 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2e870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2e880 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
2e890 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
2e8a0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
2e8b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
2e8c0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
2e8d0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2e8e0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
2e8f0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
2e900 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2e910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2e920 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
2e930 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2e940 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
2e950 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
2e960 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
2e970 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2e980 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2e990 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2e9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2e9b0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
2e9c0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
2e9d0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
2e9e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2e9f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
2ea00 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2ea10 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2ea20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2ea30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2ea40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ea50 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2ea60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2ea70 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
2ea80 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2ea90 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
2eaa0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
2eab0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2eac0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2ead0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2eae0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2eaf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2eb00 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
2eb10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2eb20 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
2eb30 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
2eb40 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
2eb50 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
2eb60 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2eb70 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2eb80 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
2eb90 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
2eba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2ebb0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2ebc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2ebd0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
2ebe0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
2ebf0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2ec00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2ec10 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2ec20 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2ec30 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2ec40 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2ec50 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2ec60 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2ec70 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2ec80 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2ec90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2eca0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
2ecb0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
2ecc0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
2ecd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
2ece0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
2ecf0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
2ed00 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
2ed10 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2ed20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2ed30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
2ed40 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2ed50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2ed60 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2ed70 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2ed80 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2ed90 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2eda0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2edb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2edc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
2edd0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
2ede0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2edf0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2ee00 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2ee10 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
2ee20 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
2ee30 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
2ee40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ee50 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2ee60 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2ee70 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2ee80 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2ee90 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
2eea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2eeb0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
2eec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2eed0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
2eee0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2eef0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2ef00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2ef10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2ef20 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
2ef30 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2ef40 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2ef50 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2ef60 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
2ef70 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2ef80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2ef90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2efa0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2efb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2efc0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2efd0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2efe0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2eff0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2f000 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2f010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f020 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2f030 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f040 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2f050 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f060 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f070 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2f080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2f0a0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
2f0b0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
2f0c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f0d0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2f0e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f0f0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2f100 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2f110 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2f120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f130 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f140 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2f150 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2f160 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2f170 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2f180 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2f190 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2f1a0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2f1b0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2f1c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2f1d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
2f1e0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
2f1f0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
2f200 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
2f210 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
2f220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f230 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2f240 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
2f250 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f260 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f270 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f280 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2f290 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2f2a0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2f2b0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2f2c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2f2d0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2f2e0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2f2f0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2f300 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2f310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f320 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2f330 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2f340 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2f350 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2f360 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2f370 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2f380 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2f390 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2f3a0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2f3b0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2f3c0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2f3d0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2f3e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2f3f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f400 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2f410 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f420 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2f430 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2f440 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2f450 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2f460 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2f470 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2f480 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
2f490 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2f4a0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2f4b0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2f4c0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2f4d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2f4e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2f4f0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
2f500 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2f510 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2f520 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2f530 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2f540 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
2f550 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2f560 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2f570 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
2f580 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2f590 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
2f5a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
2f5b0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
2f5c0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
2f5d0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
2f5e0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2f5f0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2f600 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2f610 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2f620 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2f630 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2f640 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2f650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2f660 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2f670 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2f680 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2f690 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2f6a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2f6b0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2f6c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2f6d0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2f6e0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2f6f0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2f700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f710 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2f720 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2f730 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2f740 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2f750 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2f760 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2f770 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2f780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2f790 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2f7a0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2f7b0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2f7c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2f7d0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2f7e0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2f7f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2f800 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2f810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2f820 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2f830 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2f840 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2f850 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2f860 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2f870 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2f880 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2f890 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2f8a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f8b0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2f8c0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2f8d0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2f8e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f8f0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2f900 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2f910 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2f920 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f930 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2f940 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2f950 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2f960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2f970 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2f980 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2f990 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
2f9a0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
2f9b0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
2f9c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f9d0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
2f9e0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
2f9f0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
2fa00 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
2fa10 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2fa20 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2fa30 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2fa40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2fa50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2fa60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2fa70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fa80 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2fa90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2faa0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2fab0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2fac0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fad0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2fae0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2faf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2fb00 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2fb10 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2fb20 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2fb30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2fb40 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2fb50 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2fb60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2fb70 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2fb80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2fb90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2fba0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2fbb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2fbc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2fbd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2fbe0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2fbf0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2fc00 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2fc10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fc20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2fc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fc40 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2fc50 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2fc60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fc70 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2fc80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2fc90 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2fca0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2fcb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fcc0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2fcd0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2fce0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2fcf0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2fd00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fd10 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2fd20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2fd30 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2fd40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2fd50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fd60 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2fd70 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2fd80 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2fd90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2fda0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fdb0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2fdc0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2fdd0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2fde0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2fdf0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2fe00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2fe10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fe20 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2fe30 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2fe40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2fe50 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
2fe60 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
2fe70 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
2fe80 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2fe90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2fea0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2feb0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2fec0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2fed0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2fee0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
2fef0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2ff00 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2ff10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2ff20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
2ff30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2ff40 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
2ff50 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
2ff60 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
2ff70 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ff80 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
2ff90 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
2ffa0 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
2ffb0 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
2ffc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
2ffd0 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
2ffe0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
2fff0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
30000 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
30010 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
30020 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
30030 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
30040 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
30050 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
30060 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
30070 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
30080 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
30090 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
300a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
300b0 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
300c0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
300d0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
300e0 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
300f0 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
30100 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
30110 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
30120 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
30130 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
30140 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
30150 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
30160 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
30170 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
30180 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
30190 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
301a0 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
301b0 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
301c0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
301d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
301e0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
301f0 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
30200 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
30210 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
30220 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
30230 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
30240 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
30250 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
30260 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30270 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
30280 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
30290 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
302a0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
302b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
302c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
302d0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
302e0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
302f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
30300 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
30310 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
30320 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
30330 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
30340 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
30350 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30360 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
30370 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
30380 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
30390 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
303a0 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
303b0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
303c0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
303d0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
303e0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
303f0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
30400 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
30410 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
30420 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
30430 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
30440 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30450 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
30460 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
30470 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
30480 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
30490 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
304a0 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
304b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
304c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
304d0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
304e0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
304f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30500 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
30510 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
30520 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
30530 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
30540 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
30550 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
30560 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
30570 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
30580 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
30590 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
305a0 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
305b0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
305c0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
305d0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
305e0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
305f0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
30600 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
30610 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
30620 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
30630 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
30640 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
30650 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
30660 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
30670 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
30680 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
30690 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
306a0 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
306b0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
306c0 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
306d0 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
306e0 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
306f0 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
30700 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
30710 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
30720 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
30730 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
30740 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
30750 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
30760 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
30770 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
30780 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
30790 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
307a0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
307b0 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
307c0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
307d0 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
307e0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
307f0 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
30800 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
30810 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
30820 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
30830 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
30840 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
30850 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
30860 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30870 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
30880 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
30890 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
308a0 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
308b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
308c0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
308d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
308e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
308f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
30900 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
30910 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
30920 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
30930 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
30940 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
30950 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
30960 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
30970 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
30980 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
30990 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
309a0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
309b0 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
309c0 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
309d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
309e0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
309f0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
30a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
30a10 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
30a20 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
30a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
30a40 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
30a50 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
30a60 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
30a70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30a80 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
30a90 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
30aa0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
30ab0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
30ac0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30ad0 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
30ae0 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
30af0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
30b00 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
30b10 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
30b20 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
30b30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30b40 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
30b50 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
30b60 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
30b70 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
30b80 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
30b90 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
30ba0 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
30bb0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
30bc0 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
30bd0 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
30be0 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
30bf0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
30c00 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
30c10 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
30c20 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
30c30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
30c40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
30c50 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
30c60 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
30c70 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
30c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
30c90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
30ca0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
30cb0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
30cc0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
30cd0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
30ce0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
30cf0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
30d00 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
30d10 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
30d20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30d30 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
30d40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
30d50 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
30d60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
30d70 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
30d80 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
30d90 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
30da0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
30db0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
30dc0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
30dd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
30de0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30df0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
30e00 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
30e10 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
30e20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
30e30 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
30e40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
30e50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
30e60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
30e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30e80 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
30e90 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
30ea0 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
30eb0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
30ec0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
30ed0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
30ee0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
30ef0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
30f00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
30f10 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
30f20 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
30f30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
30f40 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
30f50 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
30f60 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
30f70 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
30f80 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
30f90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
30fa0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
30fb0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
30fc0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
30fd0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
30fe0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
30ff0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
31000 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
31010 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
31020 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
31030 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
31040 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
31050 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
31060 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
31070 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
31080 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
31090 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
310a0 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
310b0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
310c0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
310d0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
310e0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
310f0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
31100 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
31110 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
31120 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
31130 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
31140 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
31150 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
31160 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31170 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
31180 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31190 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
311a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
311b0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
311c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
311d0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
311e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
311f0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
31200 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
31210 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
31220 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
31230 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
31240 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
31250 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
31260 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
31270 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
31280 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
31290 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
312a0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
312b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
312c0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
312d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
312e0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
312f0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
31300 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
31310 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31320 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
31330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31340 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
31350 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
31360 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31370 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
31380 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31390 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
313a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
313b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
313c0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
313d0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
313e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
313f0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
31400 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
31410 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
31420 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
31430 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
31440 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
31450 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
31460 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
31470 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
31480 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
31490 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
314a0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
314b0 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
314c0 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
314d0 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
314e0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
314f0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
31500 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
31510 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
31520 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
31530 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31540 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
31550 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
31560 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
31570 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
31580 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
31590 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
315a0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
315b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
315c0 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
315d0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
315e0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
315f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
31600 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
31610 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
31620 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
31630 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
31640 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
31650 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
31660 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
31670 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
31680 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
31690 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
316a0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
316b0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
316c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
316d0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
316e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
316f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
31700 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
31710 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
31720 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
31730 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
31740 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
31750 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
31760 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
31770 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
31780 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
31790 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
317a0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
317b0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
317c0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
317d0 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
317e0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
317f0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
31800 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
31810 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
31820 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
31830 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
31840 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
31850 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
31860 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
31870 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
31880 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
31890 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
318a0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
318b0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
318c0 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
318d0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
318e0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
318f0 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
31900 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
31910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
31920 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
31930 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
31940 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31950 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
31960 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
31970 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
31980 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
31990 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
319a0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
319b0 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
319c0 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
319d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
319e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
319f0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
31a00 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
31a10 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
31a20 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
31a30 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
31a40 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
31a50 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
31a60 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
31a70 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
31a80 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
31a90 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
31aa0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
31ab0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
31ac0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
31ad0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
31ae0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
31af0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
31b00 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
31b10 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
31b20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
31b30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
31b40 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
31b50 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
31b60 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
31b70 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
31b80 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
31b90 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
31ba0 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
31bb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
31bc0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
31bd0 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
31be0 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
31bf0 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
31c00 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
31c10 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  hs..*/.int sqlit
31c20 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
31c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31c40 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
31c50 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
31c60 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
31c70 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
31c80 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
31c90 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
31ca0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
31cb0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
31cc0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
31cd0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
31ce0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
31cf0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
31d00 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
31d10 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
31d20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
31d30 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
31d40 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
31d50 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
31d60 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
31d70 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
31d80 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
31d90 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
31da0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
31db0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
31dc0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
31dd0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
31de0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
31df0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
31e00 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
31e10 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
31e20 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
31e30 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
31e40 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
31e50 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
31e60 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
31e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
31e80 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
31e90 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
31ea0 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
31eb0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
31ec0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
31ed0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
31ee0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
31ef0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
31f00 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
31f10 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
31f20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
31f30 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
31f40 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
31f50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
31f60 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
31f70 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
31f80 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
31f90 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
31fa0 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
31fb0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
31fc0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
31fd0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
31fe0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
31ff0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
32000 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
32010 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
32020 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
32030 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
32040 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
32050 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
32060 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
32070 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
32080 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
32090 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
320a0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
320b0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
320c0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
320d0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
320e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
320f0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
32100 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
32110 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
32120 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
32130 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
32140 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
32150 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
32160 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32170 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
32180 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
32190 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
321a0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
321b0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
321c0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
321d0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
321e0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
321f0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
32200 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
32210 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
32220 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
32230 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
32240 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
32250 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
32260 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
32270 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
32280 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
32290 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
322a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
322b0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
322c0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
322d0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
322e0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
322f0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
32300 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
32310 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
32320 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
32330 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
32340 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
32350 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
32360 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
32370 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
32380 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
32390 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
323a0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
323b0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
323c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
323d0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
323e0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
323f0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
32400 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
32410 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
32420 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
32430 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
32440 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
32450 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
32460 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
32470 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
32480 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
32490 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
324a0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
324b0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
324c0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
324d0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
324e0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
324f0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
32500 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
32510 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
32520 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
32530 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
32540 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
32550 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
32560 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
32570 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
32580 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
32590 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
325a0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
325b0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
325c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
325d0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
325e0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
325f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
32600 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
32610 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
32620 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
32630 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
32640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
32650 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
32660 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
32670 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
32680 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
32690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
326a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
326b0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
326c0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
326d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
326e0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
326f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
32700 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
32710 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32720 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
32730 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
32740 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
32750 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
32760 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
32770 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
32780 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
32790 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
327a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
327b0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
327c0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
327d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
327e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
327f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
32800 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
32810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
32820 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
32830 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
32840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32850 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
32860 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
32870 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
32880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
328a0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
328b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
328c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
328d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
328e0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
328f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32900 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
32910 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
32920 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
32930 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
32940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
32950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32960 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
32970 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
32980 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
32990 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
329a0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
329b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
329c0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
329d0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
329e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
329f0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
32a00 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
32a10 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
32a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
32a30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
32a40 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
32a50 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
32a60 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
32a70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
32a80 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
32a90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
32aa0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
32ab0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
32ac0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
32ad0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
32ae0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
32af0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
32b00 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
32b10 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
32b20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
32b30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
32b40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
32b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32b60 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
32b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32b80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
32b90 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
32ba0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
32bb0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
32bc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
32bd0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
32be0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
32bf0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
32c00 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
32c10 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
32c20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
32c30 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
32c40 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
32c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32c60 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
32c70 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
32c80 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
32c90 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
32ca0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
32cb0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
32cc0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
32cd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
32ce0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
32cf0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
32d00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
32d10 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
32d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32d30 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
32d40 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
32d50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
32d60 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
32d70 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
32d80 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
32d90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
32da0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
32db0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
32dc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
32dd0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
32de0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
32df0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
32e00 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
32e10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
32e20 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
32e30 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
32e40 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
32e50 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
32e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32e70 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
32e80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
32e90 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
32ea0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
32eb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32ec0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
32ed0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
32ee0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
32ef0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
32f00 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
32f10 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
32f20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
32f30 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
32f40 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
32f50 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
32f60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32f70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32f80 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
32f90 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
32fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32fb0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
32fc0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
32fd0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
32fe0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
32ff0 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
33000 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
33010 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33020 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
33030 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
33040 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33050 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
33060 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
33070 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
33080 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
33090 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
330a0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
330b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
330c0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
330d0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
330e0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
330f0 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
33100 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
33110 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
33120 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
33130 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
33140 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
33150 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
33160 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
33170 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
33180 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
33190 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
331a0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
331b0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
331c0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
331d0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
331e0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
331f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
33200 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
33210 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
33220 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
33230 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
33240 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
33250 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
33260 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
33270 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
33280 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
33290 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
332a0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
332b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
332c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
332d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
332e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
332f0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
33300 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
33310 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
33320 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
33330 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
33340 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
33350 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33360 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
33370 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
33380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33390 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
333a0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
333b0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
333c0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
333d0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
333e0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
333f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
33400 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
33410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33420 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
33430 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33440 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
33450 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
33460 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
33470 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
33480 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
33490 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
334a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
334b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
334c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
334d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
334e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
334f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
33500 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
33510 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
33520 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
33530 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
33540 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
33550 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
33560 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
33570 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
33580 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
33590 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
335a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
335b0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
335c0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
335d0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
335e0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
335f0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
33600 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
33610 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
33620 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
33630 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
33640 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
33650 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
33660 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
33670 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
33680 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
33690 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
336a0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
336b0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
336c0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
336d0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
336e0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
336f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
33700 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
33710 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
33720 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
33730 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
33740 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
33750 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
33760 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
33770 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
33780 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
33790 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
337a0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
337b0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
337c0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
337d0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
337e0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
337f0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
33800 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
33810 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
33820 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
33830 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
33840 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
33850 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
33860 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
33870 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
33880 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
33890 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
338a0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
338b0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
338c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
338d0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
338e0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
338f0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
33900 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
33910 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
33920 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
33930 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
33940 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
33950 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
33960 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
33970 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
33980 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
33990 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
339a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
339b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
339c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
339d0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
339e0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
339f0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
33a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33a10 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
33a20 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
33a30 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
33a40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33a50 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
33a60 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
33a70 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
33a80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
33a90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
33aa0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
33ab0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
33ac0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
33ad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
33ae0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
33af0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
33b00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
33b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33b20 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
33b30 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
33b40 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
33b50 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
33b60 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
33b70 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
33b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33b90 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
33ba0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
33bb0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
33bc0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
33bd0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
33be0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
33bf0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
33c00 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
33c10 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
33c20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
33c30 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
33c40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
33c50 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
33c60 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
33c70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
33c80 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
33c90 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
33ca0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
33cb0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
33cc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
33cd0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
33ce0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
33cf0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
33d00 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
33d10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
33d20 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
33d30 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
33d40 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
33d50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33d60 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
33d70 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
33d80 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
33d90 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
33da0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
33db0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
33dc0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
33dd0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
33de0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
33df0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
33e00 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
33e10 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
33e20 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
33e30 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
33e40 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
33e50 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
33e60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
33e70 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
33e80 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
33e90 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
33ea0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
33eb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
33ec0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
33ed0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
33ee0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
33ef0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
33f00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
33f10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
33f20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
33f30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
33f40 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
33f50 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
33f60 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
33f70 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
33f80 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
33f90 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
33fa0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
33fb0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
33fc0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
33fd0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
33fe0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
33ff0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
34000 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
34010 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
34020 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
34030 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
34040 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
34050 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
34060 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
34070 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
34080 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
34090 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
340a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
340b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
340c0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
340d0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
340e0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
340f0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
34100 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
34110 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
34120 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
34130 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
34140 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
34150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34160 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
34170 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
34180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34190 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
341a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
341b0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
341c0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
341d0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
341e0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
341f0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
34200 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
34210 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
34220 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
34230 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
34240 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
34250 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
34260 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
34270 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
34280 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
34290 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
342a0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
342b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
342c0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
342d0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
342e0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
342f0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
34300 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
34310 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
34320 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
34330 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  y() routine is a
34340 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67   no-op returning
34350 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69   zero.** if SQLi
34360 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c  te is not compil
34370 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
34380 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
34390 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e  NAGEMENT]..*/.in
343a0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
343b0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
343c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
343d0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
343e0 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
343f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
34400 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
34410 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34420 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73  s and/or queries
34430 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d   the.** soft lim
34440 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
34450 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
34460 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
34470 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
34480 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69  .** ^SQLite stri
34490 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70  ves to keep heap
344a0 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74   memory utilizat
344b0 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  ion below the so
344c0 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74  ft heap.** limit
344d0 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65   by reducing the
344e0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
344f0 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67   held in the pag
34500 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65  e cache.** as he
34510 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73  ap memory usages
34520 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20   approaches the 
34530 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  limit..** ^The s
34540 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
34550 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  s "soft" because
34560 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c   even though SQL
34570 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73  ite strives to s
34580 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65  tay.** below the
34590 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20   limit, it will 
345a0 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74  exceed the limit
345b0 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e   rather than gen
345c0 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c  erate.** an [SQL
345d0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72  ITE_NOMEM] error
345e0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
345f0 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  s, the soft heap
34600 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64   limit .** is ad
34610 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
34620 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  ** ^The return v
34630 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
34640 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34650 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a  t64() is the siz
34660 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74  e of.** the soft
34670 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f   heap limit prio
34680 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20  r to the call.  
34690 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
346a0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
346b0 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  * then no change
346c0 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20   is made to the 
346d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
346e0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72    Hence, the cur
346f0 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  rent.** size of 
34700 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34710 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  mit can be deter
34720 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e  mined by invokin
34730 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66  g.** sqlite3_sof
34740 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
34750 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65   with a negative
34760 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
34770 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
34780 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e  t N is zero then
34790 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
347a0 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64  imit is disabled
347b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f  ..**.** ^(The so
347c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
347d0 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e   not enforced in
347e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
347f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
34800 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
34810 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69   following condi
34820 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a  tions are true:.
34830 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
34840 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70  i> The soft heap
34850 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f   limit is set to
34860 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d   zero..** <li> M
34870 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67  emory accounting
34880 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69   is disabled usi
34890 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  ng a combination
348a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
348b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
348c0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
348d0 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20  MEMSTATUS],...) 
348e0 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f  start-time optio
348f0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68  n and.**      th
34900 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  e [SQLITE_DEFAUL
34910 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d  T_MEMSTATUS] com
34920 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
34930 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74  ..** <li> An alt
34940 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61  ernative page ca
34950 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
34960 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20  on is specified 
34970 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73  using.**      [s
34980 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
34990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
349a0 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c  ACHE],...)..** <
349b0 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63  li> The page cac
349c0 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f  he allocates fro
349d0 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79  m its own memory
349e0 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a   pool supplied.*
349f0 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74  *      by [sqlit
34a00 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
34a10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
34a20 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72  CHE],...) rather
34a30 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72   than.**      fr
34a40 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20  om the heap..** 
34a50 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65  </ul>)^.**.** Be
34a60 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
34a70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
34a80 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  3, the soft heap
34a90 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
34aa0 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ed.** regardless
34ab0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
34ac0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ot the [SQLITE_E
34ad0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
34ae0 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70  AGEMENT].** comp
34af0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
34b00 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74  is invoked.  Wit
34b10 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
34b20 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
34b30 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74  NT],.** the soft
34b40 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
34b50 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79  nforced on every
34b60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34b70 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20  on.  Without.** 
34b80 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
34b90 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
34ba0 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ], the soft heap
34bb0 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65   limit is only e
34bc0 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20  nforced.** when 
34bd0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
34be0 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ted by the page 
34bf0 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20  cache.  Testing 
34c00 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65  suggests that be
34c10 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67  cause.** the pag
34c20 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70  e cache is the p
34c30 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72  redominate memor
34c40 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65  y user in SQLite
34c50 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  , most.** applic
34c60 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69  ations will achi
34c70 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66  eve adequate sof
34c80 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66  t heap limit enf
34c90 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74  orcement without
34ca0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b  .** the use of [
34cb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
34cc0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
34cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63  ..**.** The circ
34ce0 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20  umstances under 
34cf0 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c  which SQLite wil
34d00 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f  l enforce the so
34d10 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61  ft heap limit ma
34d20 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  y.** changes in 
34d30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
34d40 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71  of SQLite..*/.sq
34d50 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
34d60 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
34d70 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e  mit64(sqlite3_in
34d80 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t64 N);../*.** C
34d90 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
34da0 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69  ted Soft Heap Li
34db0 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  mit Interface.**
34dc0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
34dd0 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72  * This is a depr
34de0 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f  ecated version o
34df0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
34e00 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
34e10 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
34e20 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
34e30 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
34e40 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
34e50 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79  tibility.** only
34e60 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69  .  All new appli
34e70 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75  cations should u
34e80 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
34e90 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
34ea0 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63  it64()] interfac
34eb0 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68  e rather than th
34ec0 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54  is one..*/.SQLIT
34ed0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
34ee0 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
34ef0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29  eap_limit(int N)
34f00 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
34f10 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
34f20 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
34f30 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
34f40 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
34f50 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
34f60 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
34f70 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
34f80 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
34f90 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
34fa0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
34fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34fc0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
34fd0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
34fe0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
34ff0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
35000 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
35010 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
35020 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
35030 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35040 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
35050 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
35060 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
35070 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
35080 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35090 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
350a0 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
350b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
350c0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
350d0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
350e0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
350f0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
35100 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
35110 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
35120 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
35130 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
35140 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
35150 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
35160 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
35170 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
35180 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
35190 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
351a0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
351b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
351c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
351d0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
351e0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
351f0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
35200 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
35210 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
35220 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
35230 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
35240 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
35250 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
35260 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
35270 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
35280 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
35290 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
352a0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
352b0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
352c0 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
352d0 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
352e0 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
352f0 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
35300 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
35310 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
35320 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
35330 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
35340 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
35350 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
35360 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
35370 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
35380 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
35390 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
353a0 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
353b0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
353c0 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
353d0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
353e0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
353f0 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
35400 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
35410 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
35420 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
35430 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
35440 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
35450 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
35460 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
35470 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
35480 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
35490 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
354a0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
354b0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
354c0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
354d0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
354e0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
354f0 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
35500 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
35510 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
35520 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
35530 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
35540 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
35550 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
35560 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
35570 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
35580 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
35590 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
355a0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
355b0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
355c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
355d0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
355e0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
355f0 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
35600 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
35610 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
35620 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
35630 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
35640 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
35650 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
35660 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
35670 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
35680 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
35690 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
356a0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
356b0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
356c0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
356d0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
356e0 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
356f0 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
35700 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
35710 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
35720 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
35730 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
35740 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
35750 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
35760 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
35770 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
35780 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
35790 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
357a0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
357b0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
357c0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
357d0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
357e0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
357f0 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
35800 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
35810 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
35820 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
35830 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
35840 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
35850 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
35860 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
35870 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
35880 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
35890 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
358a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
358b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
358c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
358d0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
358e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
358f0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
35900 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
35910 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
35920 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
35930 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
35940 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
35950 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
35960 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
35970 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
35980 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
35990 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
359a0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
359b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
359c0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
359d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
359e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
359f0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
35a00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
35a10 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
35a20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
35a30 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
35a40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
35a50 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
35a60 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
35a70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35a80 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
35a90 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
35aa0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
35ab0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
35ac0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
35ad0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
35ae0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
35af0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
35b00 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
35b10 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
35b20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
35b30 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
35b40 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
35b50 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
35b60 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
35b70 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
35b80 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
35b90 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
35ba0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
35bb0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
35bc0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
35bd0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
35be0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
35bf0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
35c00 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
35c10 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
35c20 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
35c30 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
35c40 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
35c50 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
35c60 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
35c70 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
35c80 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
35c90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
35ca0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
35cb0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
35cc0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
35cd0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
35ce0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
35cf0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
35d00 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
35d10 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
35d20 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
35d30 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
35d40 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
35d50 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
35d60 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
35d70 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
35d80 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
35d90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
35da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
35db0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
35dc0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
35dd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
35de0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
35df0 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
35e00 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
35e10 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
35e20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
35e30 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
35e40 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
35e50 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
35e60 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
35e70 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
35e80 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
35e90 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
35ea0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
35eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35ec0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
35ed0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
35ee0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
35ef0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
35f00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
35f10 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
35f20 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
35f30 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
35f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
35f50 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
35f60 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
35f70 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
35f80 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
35f90 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
35fa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
35fb0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
35fc0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
35fd0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
35fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
35ff0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
36000 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36010 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
36020 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
36030 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
36040 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
36050 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
36060 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36070 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
36080 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
36090 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
360a0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
360b0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
360c0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
360d0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
360e0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
360f0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
36100 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
36110 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
36120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
36130 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
36140 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
36150 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
36160 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
36170 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
36180 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
36190 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
361a0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
361b0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
361c0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
361d0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
361e0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
361f0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
36200 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
36210 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
36220 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
36230 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
36240 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
36250 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
36260 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
36270 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
36280 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
36290 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
362a0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
362b0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
362c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
362d0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
362e0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
362f0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
36300 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
36310 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
36320 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
36330 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
36340 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
36350 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
36360 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
36370 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
36380 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
36390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
363a0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
363b0 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20  Load Statically 
363c0 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e  Linked Extension
363d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  s.**.** ^This in
363e0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
363f0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
36400 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36410 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65  invoked for.** e
36420 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
36430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
36440 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20  at is created.  
36450 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73  The idea here is
36460 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50   that.** xEntryP
36470 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e  oint() is the en
36480 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20  try point for a 
36490 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
364a0 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  d SQLite extensi
364b0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f  on.** that is to
364c0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
364d0 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c  y loaded into al
364e0 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
364f0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
36500 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20  * ^(Even though 
36510 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f  the function pro
36520 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61  totype shows tha
36530 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  t xEntryPoint() 
36540 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75  takes.** no argu
36550 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e  ments and return
36560 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69  s void, SQLite i
36570 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69  nvokes xEntryPoi
36580 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a  nt() with three.
36590 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64  ** arguments and
365a0 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74   expects and int
365b0 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69  eger result as i
365c0 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20  f the signature 
365d0 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20  of the.** entry 
365e0 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66  point where as f
365f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
36600 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
36610 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78  ** &nbsp;  int x
36620 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26  EntryPoint(.** &
36630 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33  nbsp;    sqlite3
36640 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20   *db,.** &nbsp; 
36650 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a     const char **
36660 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62  pzErrMsg,.** &nb
36670 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72  sp;    const str
36680 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
36690 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b  routines *pThunk
366a0 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a  .** &nbsp;  );.*
366b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
366c0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66  uote>)^.**.** If
366d0 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
366e0 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74   routine encount
366f0 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74  ers an error, it
36700 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a   should make *pz
36710 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20  ErrMsg.** point 
36720 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  to an appropriat
36730 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
36740 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b  (obtained from [
36750 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
36760 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72  )]).** and retur
36770 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
36780 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20   [error code].  
36790 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20  ^SQLite ensures 
367a0 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a  that *pzErrMsg.*
367b0 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65  * is NULL before
367c0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e   calling the xEn
367d0 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51  tryPoint().  ^SQ
367e0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
367f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
36800 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73  e()] on *pzErrMs
36810 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f  g after xEntryPo
36820 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20  int() returns.  
36830 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72  ^If any.** xEntr
36840 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
36850 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b   an error, the [
36860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
36870 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
36880 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
36890 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63  te3_open_v2()] c
368a0 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  all that provoke
368b0 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  d the xEntryPoin
368c0 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a  t() will fail..*
368d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
368e0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
368f0 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20  sion(X) with an 
36900 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68  entry point X th
36910 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a  at is already.**
36920 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20   on the list of 
36930 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
36940 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65  ions is a harmle
36950 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e  ss no-op. ^No en
36960 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c  try point.** wil
36970 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65  l be called more
36980 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65   than once for e
36990 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
369a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  nection that is 
369b0 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  opened..**.** Se
369c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
369d0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
369e0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  nsion()]..*/.int
369f0 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
36a00 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78  tension(void (*x
36a10 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64  EntryPoint)(void
36a20 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ));../*.** CAPI3
36a30 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d  REF: Reset Autom
36a40 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c  atic Extension L
36a50 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68  oading.**.** ^Th
36a60 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73  is interface dis
36a70 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61  ables all automa
36a80 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70  tic extensions p
36a90 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67  reviously.** reg
36aa0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
36ab0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
36ac0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  nsion()]..*/.voi
36ad0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
36ae0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
36af0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
36b00 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
36b10 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
36b20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
36b30 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
36b40 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
36b50 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
36b60 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
36b70 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
36b80 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
36b90 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
36ba0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
36bb0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
36bc0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
36bd0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
36be0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
36bf0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
36c00 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
36c10 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
36c20 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
36c30 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
36c40 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
36c50 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
36c60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
36c70 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
36c80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
36c90 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
36ca0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36cb0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
36cc0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
36cd0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
36ce0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
36cf0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
36d00 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36d10 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
36d20 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
36d30 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
36d40 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
36d50 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
36d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36d70 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
36d80 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
36d90 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
36da0 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
36db0 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
36dc0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
36dd0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
36de0 64 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  d a "virtual tab
36df0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
36e00 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
36e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
36e20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
36e30 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
36e40 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
36e50 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
36e60 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
36e70 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
36e80 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
36e90 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
36ea0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
36eb0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
36ec0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36ed0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
36ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
36ef0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
36f00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36f10 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
36f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36f30 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
36f40 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
36f50 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
36f60 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
36f70 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
36f80 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
36f90 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
36fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
36fb0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
36fc0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
36fd0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
36fe0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
36ff0 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
37000 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
37010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
37020 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37030 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
37040 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
37050 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
37060 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
37070 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
37080 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
37090 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
370a0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
370b0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
370c0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
370d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
370e0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
370f0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
37100 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
37110 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
37120 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
37130 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
37140 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
37150 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
37160 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
37170 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37180 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
37190 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
371a0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
371b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
371c0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
371d0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
371e0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
371f0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
37200 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
37210 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
37220 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
37230 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
37240 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
37250 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
37260 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
37270 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
37280 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
37290 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
372a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
372b0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
372c0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
372d0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
372e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
372f0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
37300 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
37310 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
37320 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
37330 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37340 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
37350 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
37360 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
37370 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
37380 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
37390 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
373a0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
373b0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
373c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
373d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
373e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
373f0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
37400 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
37410 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
37420 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37430 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
37440 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37450 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
37460 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
37470 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37480 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
37490 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
374a0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
374b0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
374c0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
374d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
374e0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
374f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
37500 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
37510 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
37520 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37530 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
37540 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
37550 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
37560 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
37570 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74  w);.  /* The met
37580 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
37590 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
375a0 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65  he sqlite_module
375b0 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a   object. Those .
375c0 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66    ** below are f
375d0 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  or version 2 and
375e0 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69   greater. */.  i
375f0 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29  nt (*xSavepoint)
37600 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37610 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  VTab, int);.  in
37620 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71  t (*xRelease)(sq
37630 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37640 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  b, int);.  int (
37650 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71  *xRollbackTo)(sq
37660 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37670 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a  b, int);.};../*.
37680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
37690 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
376a0 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
376b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
376c0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
376d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
376e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
376f0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
37700 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
37710 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
37720 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
37730 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
37740 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
37750 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
37760 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
37770 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
37780 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
37790 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
377a0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
377b0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
377c0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
377d0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
377e0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
377f0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
37800 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
37810 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
37820 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
37830 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
37840 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
37850 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
37860 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
37870 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
37880 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
37890 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
378a0 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
378b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
378c0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
378d0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
378e0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
378f0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
37900 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
37910 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
37920 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
37930 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
37940 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
37950 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
37960 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
37970 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
37980 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
37990 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
379a0 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
379b0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
379c0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
379d0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
379e0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
379f0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
37a00 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
37a10 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
37a20 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
37a30 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
37a40 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
37a50 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
37a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
37a70 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
37a80 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
37a90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
37aa0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
37ab0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
37ac0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
37ad0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
37ae0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
37af0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
37b00 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
37b10 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
37b20 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
37b30 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
37b40 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
37b50 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
37b60 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
37b70 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
37b80 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
37b90 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
37ba0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
37bb0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
37bc0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
37bd0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
37be0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
37bf0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
37c00 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
37c10 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
37c20 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
37c30 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
37c40 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
37c50 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
37c60 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
37c70 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
37c80 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
37c90 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
37ca0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
37cb0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
37cc0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
37cd0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
37ce0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
37cf0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
37d00 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
37d10 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
37d20 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
37d30 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
37d40 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
37d50 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
37d60 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
37d70 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
37d80 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
37d90 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
37da0 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
37db0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
37dc0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
37dd0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
37de0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
37df0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
37e00 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
37e10 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
37e20 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
37e30 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
37e40 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
37e50 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
37e60 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
37e70 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
37e80 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
37e90 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
37ea0 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
37eb0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
37ec0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
37ed0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
37ee0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
37ef0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
37f00 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
37f10 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
37f20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
37f30 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
37f40 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
37f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
37f60 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
37f70 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
37f80 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
37f90 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
37fa0 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
37fb0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
37fc0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
37fd0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
37fe0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
37ff0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
38000 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
38010 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
38020 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
38030 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
38040 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
38050 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
38060 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
38070 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
38080 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
38090 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
380a0 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
380b0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
380c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
380d0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
380e0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
380f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
38100 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
38110 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
38120 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
38130 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
38140 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
38150 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
38160 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
38170 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
38180 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
38190 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
381a0 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
381b0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
381c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
381d0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
381e0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
381f0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
38200 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
38210 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
38220 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
38230 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
38240 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
38250 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38260 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
38270 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
38280 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
38290 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
382a0 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
382b0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
382c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
382d0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
382e0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
382f0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
38300 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
38310 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
38320 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
38330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38340 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
38350 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
38360 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
38370 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
38380 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
38390 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
383a0 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
383b0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
383c0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
383d0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
383e0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
383f0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
38400 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
38410 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
38420 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
38430 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
38440 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
38450 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
38460 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
38470 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
38480 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
38490 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
384a0 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
384b0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
384c0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
384d0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
384e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
384f0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
38500 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
38510 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
38520 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
38530 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
38540 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
38550 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
38560 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
38570 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
38580 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
38590 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
385a0 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
385b0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
385c0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
385d0 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70  le Constraint Op
385e0 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a  erator Codes.**.
385f0 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
38600 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f  defined the allo
38610 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74  wed values for t
38620 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  he.** [sqlite3_i
38630 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73  ndex_info].aCons
38640 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
38650 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72  d.  Each value r
38660 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20  epresents.** an 
38670 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73  operator that is
38680 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74   part of a const
38690 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68  raint term in th
386a0 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e wHERE clause o
386b0 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61  f.** a query tha
386c0 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61  t uses a [virtua
386d0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65  l table]..*/.#de
386e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
386f0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
38700 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
38710 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
38720 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
38730 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
38740 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
38750 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
38760 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
38770 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
38780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
38790 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
387a0 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
387b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
387c0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
387d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
387e0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
387f0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
38800 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  entation.**.** ^
38810 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
38820 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
38830 74 65 72 20 61 20 6e 65 7