/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 628de30f6063695288eadf34c167e49bc34c9828:


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 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5160: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
5170: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
5180: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
5190: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
51a0: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
51b0: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
51c0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
51d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
51e0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
51f0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
5200: 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65  eter to the xOpe
5210: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
5220: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
5230: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
5240: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5250: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5260: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5270: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5280: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
52a0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
52b0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
52c0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
52d0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
52f0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5300: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5310: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5320: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5340: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5350: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5360: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5380: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5390: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
53a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53c0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
53d0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
53e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5400: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5410: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5420: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5440: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5450: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5460: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5480: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5490: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
54a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
54c0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
54d0: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
54e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5500: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5510: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5520: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5530: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5540: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5550: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5560: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5580: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5590: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
55a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
55c0: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
55d0: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
55e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
55f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5610: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5620: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5630: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5640: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5660: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
5670: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
5680: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5690: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
56b0: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
56c0: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
56d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
56e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5700: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
5710: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
5720: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
5730: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
5740: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5750: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
5760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5770: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5780: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
5790: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
57a0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
57b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
57c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
57d0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
57e0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
57f0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
5800: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
5810: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
5820: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
5830: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
5840: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
5850: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
5860: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
5870: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5880: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
5890: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
58a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58b0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
58c0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
58d0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
58e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
58f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5900: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5910: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
5920: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
5930: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
5940: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
5950: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
5960: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
5970: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5980: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5990: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
59a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
59b0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
59c0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
59d0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
59e0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
59f0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5a00: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5a10: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5a20: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5a30: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5a40: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5a50: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5a60: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5a70: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5a80: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5a90: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5aa0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5ab0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5ac0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
5af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5b10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
5b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b70: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b90: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
5ba0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5bc0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5bd0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5be0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5bf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c00: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
5c10: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c30: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5c40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c50: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5c60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5c70: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5c80: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
5c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ca0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5cb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5cc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5cd0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5ce0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
5cf0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5d00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5d10: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
5d20: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5d40: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
5d50: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
5d60: 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000800../*.** CA
5d70: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5d80: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
5d90: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
5da0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
5db0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
5dc0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
5dd0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
5de0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
5df0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
5e00: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
5e10: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
5e20: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
5e30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5e40: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
5e50: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
5e60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5e70: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e90: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
5ea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5eb0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
5ec0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
5ed0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5ee0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
5ef0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
5f00: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
5f10: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
5f20: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
5f30: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
5f40: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
5f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5f60: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
5f70: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
5f80: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
5f90: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5fa0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
5fb0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
5fc0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
5fd0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
5fe0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
5ff0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6000: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6010: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6020: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6030: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6040: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6050: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6060: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6070: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6080: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6090: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
60a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
60b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
60c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
60d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
60e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
60f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6100: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6110: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6120: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6130: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6140: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6150: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6160: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6170: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6180: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6190: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
61a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
61b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
61c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
61d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
61e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
61f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6200: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6210: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6220: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6230: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6240: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6250: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6260: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6270: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6280: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6290: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
62a0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
62b0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
62c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
62d0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
62e0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
62f0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6300: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6310: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6320: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6330: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6340: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6350: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6360: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6370: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6380: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6390: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
63a0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
63b0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
63c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
63d0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
63e0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
63f0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6410: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6420: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6430: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6440: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6450: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6460: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6470: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6480: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6490: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
64a0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
64b0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
64c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
64d0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
64e0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
64f0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6500: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6510: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6520: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6530: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6540: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6550: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6560: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6570: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6580: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6590: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
65a0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
65b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
65c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
65d0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
65e0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
65f0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6600: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6610: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6620: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6630: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6640: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6650: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6660: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6670: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6680: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6690: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
66a0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
66b0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
66c0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
66d0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
66e0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
66f0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6700: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6710: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
6720: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70  xOpen method pop
6730: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6740: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6750: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6760: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6770: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6780: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6790: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
67a0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
67b0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
67c0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
67d0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
67e0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
67f0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
6800: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
6810: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
6820: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
6830: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6840: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
6850: 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  If the xOpen met
6860: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
6870: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6880: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
6890: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
68a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
68b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
68d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
68e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f  d even if the xO
68f0: 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61  pen reported tha
6900: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
6910: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
6920: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
6930: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
6940: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70  ing a failed xOp
6950: 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  en.** is for the
6960: 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68   xOpen to set th
6970: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6980: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
6990: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
69a0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
69b0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
69c0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
69d0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
69e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
69f0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6a00: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6a10: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6a20: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6a30: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6a40: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6a50: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6a60: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6a70: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6a80: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6a90: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6aa0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6ab0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6ac0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6ad0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6ae0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6af0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6b00: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6b10: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6b20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6b30: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6b40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6b50: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6b60: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6b70: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6b80: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6b90: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6ba0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6bb0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6bc0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6bd0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6be0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6bf0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6c00: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6c10: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6c20: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6c30: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6c40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6c50: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6c60: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6c70: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6c80: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6c90: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6ca0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6cb0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6cc0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6cd0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6ce0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6cf0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6d00: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6d10: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6d20: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6d30: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6d40: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6d50: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6d60: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6d70: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6d80: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6d90: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6da0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6db0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6dc0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6dd0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6de0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6df0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6e00: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
6e10: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
6e20: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
6e30: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
6e40: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
6e50: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
6e60: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
6e70: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
6e80: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
6e90: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
6ea0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
6eb0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
6ec0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
6ed0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
6ee0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
6ef0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
6f00: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
6f10: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
6f20: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
6f30: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
6f40: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
6f50: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
6f60: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
6f70: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
6f80: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
6f90: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
6fa0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
6fb0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
6fc0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
6fd0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
6fe0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
6ff0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7000: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7010: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7020: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7030: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7040: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7050: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7060: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7070: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7080: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7090: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
70a0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
70b0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
70c0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
70d0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
70e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
70f0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7100: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7110: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7120: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7130: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7140: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7150: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7160: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
7170: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
7180: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
7190: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
71a0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
71b0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
71c0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
71d0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
71e0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
71f0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
7200: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7210: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7220: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7230: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7240: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7250: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7260: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
7270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7280: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
72a0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
72b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
72c0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
72d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
72e0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
72f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7300: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7310: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7320: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7330: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7340: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7350: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7360: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
7370: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7380: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7390: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
73a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
73c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
73d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
73e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
73f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7400: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7410: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7420: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7430: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7440: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7450: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7460: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7470: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7480: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7490: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
74a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
74b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
74c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
74d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
74e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
74f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
7500: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7510: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7520: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7530: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7540: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7550: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7560: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7570: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7580: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7590: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
75a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
75b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
75c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
75d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
75e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
75f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
7600: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7610: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7620: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7630: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7640: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7650: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
7660: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
7670: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7680: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7690: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
76a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
76b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
76c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
76d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
76e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
76f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7700: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7710: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7720: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7730: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7740: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7750: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
7760: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7770: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7780: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7790: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
77a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
77b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
77c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
77d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
77e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
77f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7800: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7810: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7820: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7830: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7840: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7850: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
7860: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7870: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7880: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7890: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
78a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
78b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
78c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
78d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
78e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
78f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7900: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7910: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7920: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7930: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7940: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7950: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7960: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7970: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7980: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7990: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
79a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
79b0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
79c0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
79d0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
79e0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
79f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
7a10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
7a20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
7a30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
7a40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
7a50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
7a60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7a70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7a80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7a90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
7aa0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7ab0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7ac0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7ad0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7ae0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7af0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7b00: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
7b10: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
7b20: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
7b30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
7b40: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
7b50: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
7b60: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7b70: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7b80: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7b90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7ba0: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7bb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7bc0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7be0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7bf0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7c00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7c10: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
7c20: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
7c30: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
7c40: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
7c50: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
7c60: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7c70: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7c80: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7c90: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7cb0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7cc0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7cd0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ce0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7cf0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7d10: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
7d20: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
7d30: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
7d40: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
7d50: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
7d60: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7d70: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7d80: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7d90: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7da0: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7db0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7dc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7dd0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7de0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7df0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7e00: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
7e10: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
7e20: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
7e30: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
7e40: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
7e50: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
7e60: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
7e70: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
7e80: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
7e90: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
7ea0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
7eb0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
7ec0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
7ed0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
7ee0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
7ef0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
7f00: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
7f10: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
7f20: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
7f30: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
7f40: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7f50: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
7f60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7f70: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
7f80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
7f90: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
7fa0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
7fb0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
7fc0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
7fd0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
7fe0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
7ff0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
8000: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8010: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8020: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8030: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8040: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8050: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8060: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8070: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8080: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8090: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
80a0: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
80b0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
80c0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
80d0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
80e0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
80f0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
8100: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8110: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystems..**.** Th
8120: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8130: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8140: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8150: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8160: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8170: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8180: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8190: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
81a0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
81b0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
81c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
81d0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
81e0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
81f0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
8200: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ion..**.** ^(The
8210: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8220: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8230: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8240: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8250: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8260: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8270: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8280: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8290: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
82a0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
82b0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
82c0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
82d0: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
82e0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
82f0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8300: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8310: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8320: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8330: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8340: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8350: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8360: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8370: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8380: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8390: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
83a0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
83b0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
83c0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
83d0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
83e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
83f0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
8400: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8410: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8420: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
8430: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8440: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
8450: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23  quire it.  .*/.#
8460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8470: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
8480: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
8490: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
84a0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
84b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
84c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
84d0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
84e0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
84f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
8500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8510: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
8520: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
8530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8540: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23  K_SIZE       6.#
8550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8560: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8570: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
8580: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8590: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 38 0a 0a  _OMITTED     8..
85a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
85b0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
85c0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
85d0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
85e0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
85f0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
8600: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
8610: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
8620: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
8630: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
8640: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
8650: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
8660: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
8670: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
8680: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
8690: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
86a0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
86b0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
86c0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
86d0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
86e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
86f0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
8700: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8710: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
8720: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
8730: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
8740: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
8750: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
8760: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
8770: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
8780: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
8790: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
87a0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
87b0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
87c0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
87d0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
87e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
87f0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
8800: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
8810: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
8820: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
8830: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
8840: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
8850: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
8860: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
8870: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
8880: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
8890: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
88a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
88b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
88c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
88d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
88e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
88f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
8900: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
8910: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
8920: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
8930: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
8940: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
8950: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
8960: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
8970: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
8980: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
8990: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
89a0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
89b0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
89c0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
89d0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
89e0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
89f0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
8a00: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
8a10: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
8a20: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
8a30: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
8a40: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
8a50: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
8a60: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
8a70: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
8a80: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
8a90: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
8aa0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
8ab0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
8ac0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
8ad0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
8ae0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
8af0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
8b00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
8b10: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
8b20: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
8b30: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
8b40: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8b50: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
8b60: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
8b70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
8b80: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
8b90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
8ba0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
8bb0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
8bc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
8bd0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
8be0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
8bf0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
8c00: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
8c10: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
8c20: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
8c30: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
8c40: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
8c50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
8c60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
8c70: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
8c80: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
8c90: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
8ca0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
8cb0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
8cc0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
8cd0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
8ce0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
8cf0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
8d00: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
8d10: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
8d20: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
8d30: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  es..**.** ^SQLit
8d40: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
8d50: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
8d60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
8d70: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
8d80: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
8d90: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
8da0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
8db0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
8dc0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
8dd0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
8de0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
8df0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
8e00: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
8e10: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
8e20: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
8e30: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
8e40: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
8e50: 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e  han.** 10 alphan
8e60: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
8e70: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
8e80: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
8e90: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
8ea0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
8eb0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
8ec0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
8ed0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
8ee0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
8ef0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
8f00: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
8f10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8f20: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
8f30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
8f40: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
8f50: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
8f60: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
8f70: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
8f80: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
8f90: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8fa0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
8fb0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
8fc0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
8fd0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
8fe0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
8ff0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
9000: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
9010: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
9020: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
9030: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
9040: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
9050: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
9060: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
9070: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
9080: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
9090: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
90a0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
90b0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
90c0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
90d0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
90e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
90f0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
9100: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
9110: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
9120: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
9130: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
9140: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
9150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
9160: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
9170: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
9180: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
9190: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
91a0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
91b0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
91c0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
91d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
91e0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
91f0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
9200: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
9210: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
9220: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
9230: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
9240: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
9250: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
9260: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
9270: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
9280: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
9290: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
92a0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
92b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
92c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
92d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
92e0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
92f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9300: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
9310: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9320: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
9330: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
9340: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
9350: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
9360: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
9370: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
9380: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9390: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
93a0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
93b0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
93c0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
93d0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
93e0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
93f0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
9400: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
9410: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
9420: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
9430: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
9440: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
9450: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
9460: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
9470: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
9480: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
9490: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
94a0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
94b0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
94c0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
94d0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
94e0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
94f0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
9500: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
9510: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
9520: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
9530: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
9540: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
9550: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
9560: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
9570: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
9580: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
9590: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
95a0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
95b0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
95c0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
95d0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
95e0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
95f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
9600: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9610: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
9620: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
9630: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
9640: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
9650: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
9660: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9670: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
9680: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
9690: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
96a0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
96b0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
96c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
96d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
96e0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
96f0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
9700: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
9710: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
9720: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
9730: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
9740: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9750: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
9760: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
9770: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
9780: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
9790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
97a0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
97b0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
97c0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
97d0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
97e0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
97f0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
9800: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
9810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
9820: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
9830: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
9840: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
9850: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
9860: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9870: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
9880: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
9890: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
98a0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
98b0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
98c0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
98d0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
98e0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
98f0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
9900: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
9910: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
9920: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
9930: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
9940: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
9950: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
9960: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
9970: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
9980: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
9990: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
99a0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
99b0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
99c0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
99d0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
99e0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
99f0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
9a00: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
9a10: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
9a20: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
9a30: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
9a40: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
9a50: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
9a60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
9a70: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
9a80: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
9a90: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
9aa0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
9ab0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
9ac0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
9ad0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
9ae0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
9af0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
9b00: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
9b10: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
9b20: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
9b30: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
9b40: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
9b50: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
9b60: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
9b70: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
9b80: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9b90: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
9ba0: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
9bb0: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
9bc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9bd0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
9be0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
9bf0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
9c00: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
9c10: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9c20: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
9c30: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9c40: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
9c50: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
9c60: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
9c70: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
9c80: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
9c90: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
9ca0: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
9cb0: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
9cc0: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
9cd0: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
9ce0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
9cf0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
9d00: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
9d10: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
9d20: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
9d30: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
9d40: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
9d50: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
9d60: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
9d70: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
9d80: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
9d90: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
9da0: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
9db0: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
9dc0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9dd0: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
9de0: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
9df0: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
9e00: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
9e10: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
9e20: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
9e30: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
9e40: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
9e50: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
9e60: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
9e70: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
9e80: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
9e90: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
9ea0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
9eb0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
9ec0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
9ed0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
9ee0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9ef0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9f00: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
9f10: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
9f20: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
9f30: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
9f40: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
9f50: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
9f60: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9f70: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9f80: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
9f90: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
9fa0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
9fb0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
9fc0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
9fd0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
9fe0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9ff0: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
a000: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
a010: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
a020: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
a030: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
a040: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
a050: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
a060: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
a070: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
a080: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
a090: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
a0a0: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
a0b0: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
a0c0: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
a0d0: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65 64 20 62  mber multipled b
a0e0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
a0f0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
a100: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
a110: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
a120: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
a130: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
a140: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
a150: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
a160: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
a170: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
a180: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
a190: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
a1a0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
a1b0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
a1c0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
a1d0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
a1e0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
a1f0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
a200: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
a210: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
a220: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
a230: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
a240: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
a250: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
a260: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
a270: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
a280: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
a290: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
a2a0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
a2b0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
a2c0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
a2d0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
a2e0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
a2f0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
a300: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
a310: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
a320: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
a330: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
a340: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
a350: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
a360: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
a370: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
a380: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
a390: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
a3a0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
a3b0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
a3c0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
a3d0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
a3e0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
a3f0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
a400: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
a410: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
a420: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
a430: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
a440: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
a450: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
a460: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
a470: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
a480: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
a490: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
a4a0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
a4b0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
a4c0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
a4d0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
a4e0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
a4f0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
a500: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
a510: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
a520: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
a530: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
a540: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
a550: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
a560: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
a570: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
a580: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
a590: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
a5a0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
a5b0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
a5c0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
a5d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
a5e0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
a5f0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
a600: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
a610: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
a620: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
a630: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
a640: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
a650: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
a660: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
a670: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
a680: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
a690: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
a6a0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
a6b0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
a6c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a6d0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
a6e0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
a6f0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
a700: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
a710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
a720: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
a730: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
a740: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
a750: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
a760: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a770: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
a780: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
a790: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
a7a0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
a7b0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
a7c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a7d0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a7e0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
a7f0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
a800: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a810: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a820: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
a830: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
a840: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
a850: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a860: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
a870: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
a880: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
a890: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
a8a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a8b0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
a8c0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
a8d0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
a8e0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
a8f0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
a900: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
a910: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
a920: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
a930: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
a940: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
a950: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
a960: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
a970: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
a980: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
a990: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
a9a0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
a9b0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
a9c0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
a9d0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
a9e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
a9f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
aa00: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
aa10: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
aa20: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
aa30: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
aa40: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
aa50: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
aa60: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
aa70: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
aa80: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
aa90: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
aaa0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
aab0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
aac0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
aad0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
aae0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
aaf0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
ab00: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ab10: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ab20: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ab30: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ab40: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ab50: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
ab60: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
ab70: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
ab80: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
ab90: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
aba0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
abb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
abc0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
abd0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
abe0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
abf0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ac00: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ac10: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ac20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ac30: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ac40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ac50: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ac60: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ac70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ac80: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
ac90: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
aca0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
acb0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
acc0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
acd0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
ace0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
acf0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
ad00: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
ad10: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
ad20: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
ad30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ad40: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
ad50: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
ad60: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
ad70: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
ad80: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
ad90: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
ada0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
adb0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
adc0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
add0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
ade0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
adf0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
ae00: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
ae10: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
ae20: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
ae30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ae40: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
ae50: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
ae60: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
ae70: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
ae80: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ae90: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
aea0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
aeb0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
aec0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
aed0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
aee0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
aef0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
af00: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
af10: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
af20: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
af30: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
af40: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
af50: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
af60: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
af70: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
af80: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
af90: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
afa0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
afb0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
afc0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
afd0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
afe0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
aff0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
b000: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b010: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
b020: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
b030: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
b040: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
b050: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
b060: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
b070: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
b080: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
b090: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
b0a0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
b0b0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
b0c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b0d0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
b0e0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
b0f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b100: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
b110: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
b120: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
b130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b140: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
b150: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
b160: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
b170: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
b180: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
b190: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
b1a0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
b1b0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
b1c0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
b1d0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
b1e0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
b1f0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
b200: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b210: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
b220: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
b230: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
b240: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
b250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
b260: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
b270: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
b280: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b290: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
b2a0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
b2b0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b2c0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
b2d0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
b2e0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
b2f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
b300: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
b310: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
b320: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
b330: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
b340: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
b350: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
b360: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
b370: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
b380: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
b390: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
b3a0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
b3b0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
b3c0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
b3d0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
b3e0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
b3f0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
b400: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
b410: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
b420: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
b430: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
b440: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
b450: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
b460: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
b470: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
b480: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
b490: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
b4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
b4b0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
b4c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
b4d0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
b4e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b4f0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
b500: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
b510: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
b520: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
b530: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
b540: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
b550: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
b560: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
b570: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
b580: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
b590: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
b5a0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
b5b0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
b5c0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
b5d0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
b5e0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
b5f0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
b600: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
b610: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
b620: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
b630: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
b640: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b650: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
b660: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
b670: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
b680: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
b690: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
b6a0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
b6b0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
b6c0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
b6d0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
b6e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
b6f0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
b700: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
b710: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
b720: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
b730: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
b740: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
b750: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
b760: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
b770: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
b780: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
b790: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
b7a0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
b7b0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
b7c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
b7d0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
b7e0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
b7f0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
b800: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
b810: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b820: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
b830: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
b840: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
b850: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
b860: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
b870: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b880: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
b890: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
b8a0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
b8b0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
b8c0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
b8d0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
b8e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
b8f0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
b900: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
b910: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
b920: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
b930: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
b940: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
b950: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
b960: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
b970: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
b980: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
b990: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
b9a0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
b9b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9c0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
b9d0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
b9e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
b9f0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
ba00: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
ba10: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
ba20: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
ba30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
ba40: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ba50: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
ba60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ba70: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
ba80: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
ba90: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
baa0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
bab0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
bac0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
bad0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
bae0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
baf0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
bb00: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
bb10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
bb20: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
bb30: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
bb40: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
bb50: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
bb60: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
bb70: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
bb80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
bb90: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
bba0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
bbb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
bbc0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
bbd0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
bbe0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
bbf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
bc00: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
bc10: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
bc20: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
bc30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bc40: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
bc50: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
bc60: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
bc70: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
bc80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
bc90: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
bca0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
bcb0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
bcc0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
bcd0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
bce0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
bcf0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
bd00: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
bd10: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
bd20: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
bd30: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
bd40: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
bd50: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
bd60: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
bd70: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
bd80: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
bd90: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
bda0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
bdb0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
bdc0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
bdd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
bde0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
bdf0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
be00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
be10: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
be20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
be30: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
be40: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
be50: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
be60: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
be70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
be80: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
be90: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
bea0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
beb0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
bec0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
bed0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
bee0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
bef0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
bf00: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
bf10: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
bf20: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
bf30: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
bf40: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
bf50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
bf60: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
bf70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
bf80: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
bf90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
bfa0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
bfb0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
bfc0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
bfd0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
bfe0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
bff0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
c000: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
c010: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
c020: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
c030: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
c040: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
c050: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
c060: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
c070: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
c080: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
c090: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
c0a0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
c0b0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c0c0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
c0d0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
c0e0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
c0f0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
c100: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
c110: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
c120: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
c130: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c140: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
c150: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
c160: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
c170: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
c180: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
c190: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
c1a0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
c1b0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
c1c0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
c1d0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
c1e0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
c1f0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
c200: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
c210: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
c220: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
c230: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
c240: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
c250: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
c260: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
c270: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
c280: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
c290: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
c2a0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
c2b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
c2c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
c2d0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
c2e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
c2f0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
c300: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
c310: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
c320: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
c330: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
c340: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c350: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
c360: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
c370: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
c380: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
c390: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
c3a0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
c3b0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
c3c0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
c3d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c3e0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
c3f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
c400: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
c410: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
c420: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
c430: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
c440: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
c450: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
c460: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
c470: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
c480: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
c490: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
c4a0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
c4b0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
c4c0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
c4d0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
c4e0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
c4f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
c500: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
c510: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
c520: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
c530: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
c540: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
c550: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
c560: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
c570: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
c580: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
c590: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
c5a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c5b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
c5c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
c5d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
c5e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c5f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
c600: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
c610: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
c620: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
c630: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
c640: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
c650: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c660: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
c670: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
c680: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
c690: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
c6a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
c6b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
c6c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
c6d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
c6e0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
c6f0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
c700: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
c710: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
c720: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
c730: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
c740: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
c750: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
c760: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c770: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
c780: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
c790: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
c7a0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
c7b0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
c7c0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
c7d0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
c7e0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
c7f0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
c800: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
c810: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
c820: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
c830: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c840: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
c850: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
c860: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
c870: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
c880: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
c890: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
c8a0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
c8b0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
c8c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
c8d0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
c8e0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
c8f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
c900: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
c910: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
c920: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
c930: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
c940: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
c950: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
c960: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
c970: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c980: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
c990: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
c9a0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
c9b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c9c0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
c9d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
c9e0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
c9f0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
ca00: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
ca10: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
ca20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ca30: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
ca40: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
ca50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ca60: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
ca70: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
ca80: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
ca90: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
caa0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
cab0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
cac0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
cad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
cae0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
caf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
cb00: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
cb10: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
cb20: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
cb30: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
cb40: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
cb50: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
cb60: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
cb70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
cb80: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
cb90: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cba0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
cbb0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
cbc0: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
cbd0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cbe0: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
cbf0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
cc00: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
cc10: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
cc20: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
cc30: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
cc40: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
cc50: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
cc60: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
cc70: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
cc80: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
cc90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
cca0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
ccb0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
ccc0: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
ccd0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
cce0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
ccf0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
cd00: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
cd10: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
cd20: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
cd30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cd40: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
cd50: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
cd60: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
cd70: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
cd80: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
cd90: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
cda0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
cdb0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
cdc0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
cdd0: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
cde0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
cdf0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
ce00: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
ce10: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
ce20: 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
ce30: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
ce40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
ce50: 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
ce60: 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
ce70: 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
ce80: 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
ce90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cea0: 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
ceb0: 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
cec0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
ced0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
cee0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
cef0: 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
cf00: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
cf10: 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
cf20: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
cf30: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
cf40: 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
cf50: 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
cf60: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
cf70: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
cf80: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
cf90: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
cfa0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
cfb0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
cfc0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
cfd0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
cfe0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
cff0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
d000: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
d010: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
d020: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
d030: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
d040: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
d050: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
d060: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
d070: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
d080: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
d090: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
d0a0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
d0b0: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
d0c0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
d0d0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
d0e0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
d0f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
d100: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
d110: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
d120: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
d130: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
d140: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
d150: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
d160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
d170: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
d180: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
d190: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
d1a0: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
d1b0: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
d1c0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
d1d0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d1e0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
d1f0: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
d200: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
d210: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
d220: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
d230: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
d240: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
d250: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
d260: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
d270: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
d280: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
d290: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
d2a0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
d2b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
d2c0: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
d2d0: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
d2e0: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
d2f0: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
d300: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
d310: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
d320: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
d330: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
d340: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
d350: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
d360: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
d370: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
d380: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
d390: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
d3a0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
d3b0: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
d3c0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
d3d0: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
d3e0: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
d3f0: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
d400: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
d410: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
d420: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
d430: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
d440: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
d450: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
d460: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
d470: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
d480: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
d490: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
d4a0: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
d4b0: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
d4c0: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
d4d0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d4e0: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
d4f0: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
d500: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
d510: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
d520: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
d530: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
d540: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
d550: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
d560: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
d570: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
d580: 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61  on.  ^SQLite gua
d590: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
d5a0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
d5b0: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
d5c0: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
d5d0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
d5e0: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
d5f0: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
d600: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
d610: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
d620: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
d630: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
d640: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
d650: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
d660: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
d670: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
d680: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
d690: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
d6a0: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
d6b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
d6c0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
d6d0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d6e0: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
d6f0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
d700: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
d710: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
d720: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
d730: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
d740: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
d750: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
d760: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
d770: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
d780: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
d790: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
d7a0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
d7b0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
d7c0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
d7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d7e0: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
d7f0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
d800: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
d810: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
d820: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
d830: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
d840: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
d850: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
d860: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
d870: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
d880: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
d890: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
d8a0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
d8b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d8c0: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
d8d0: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
d8e0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
d8f0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
d900: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
d910: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
d920: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
d930: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
d940: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
d950: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
d960: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
d970: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
d980: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
d990: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
d9a0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
d9b0: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
d9c0: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
d9d0: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
d9e0: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
d9f0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
da00: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
da10: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
da20: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
da30: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
da40: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
da50: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
da60: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
da70: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
da80: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
da90: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
daa0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
dab0: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
dac0: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
dad0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
dae0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
daf0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
db00: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
db10: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
db20: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
db30: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
db40: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
db50: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
db60: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
db70: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
db80: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
db90: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
dba0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
dbb0: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
dbc0: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
dbd0: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
dbe0: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
dbf0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
dc00: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
dc10: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
dc20: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
dc30: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
dc40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
dc50: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
dc60: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
dc70: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
dc80: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
dc90: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
dca0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
dcb0: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
dcc0: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
dcd0: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
dce0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
dcf0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
dd00: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
dd10: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
dd20: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
dd30: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
dd40: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
dd50: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
dd60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
dd70: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
dd80: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
dd90: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
dda0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
ddb0: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
ddc0: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
ddd0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
dde0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
ddf0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
de00: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
de10: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
de20: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
de30: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
de40: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
de50: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
de60: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
de70: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
de80: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
de90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
dea0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
deb0: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
dec0: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
ded0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
dee0: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
def0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
df00: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
df10: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
df20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
df30: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
df40: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
df50: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
df60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
df70: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
df80: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
df90: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
dfa0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
dfb0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
dfc0: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
dfd0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
dfe0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
dff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e000: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
e010: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
e020: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
e030: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
e040: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
e050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e060: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
e070: 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
e080: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
e090: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
e0a0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
e0b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
e0c0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
e0d0: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
e0e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
e0f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e100: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
e110: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
e120: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
e130: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
e140: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
e150: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
e160: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
e170: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
e180: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
e190: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
e1a0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
e1b0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
e1c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
e1d0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
e1e0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
e1f0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
e200: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
e210: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
e220: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
e230: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
e240: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
e250: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
e260: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
e270: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
e280: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
e290: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
e2a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
e2b0: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
e2c0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
e2d0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
e2e0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
e2f0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
e300: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
e310: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
e320: 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
e330: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
e340: 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
e350: 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
e360: 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
e370: 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
e380: 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
e390: 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
e3a0: 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
e3b0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
e3c0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
e3d0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
e3e0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
e3f0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
e400: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
e410: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
e420: 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
e430: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e440: 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
e450: 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
e460: 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
e470: 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
e480: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
e490: 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
e4a0: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
e4b0: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
e4c0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
e4d0: 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
e4e0: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e4f0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e500: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
e510: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
e520: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
e530: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e540: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
e550: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
e560: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
e570: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
e580: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
e590: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
e5a0: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
e5b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e5c0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
e5d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
e5e0: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
e5f0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
e600: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
e610: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
e620: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
e630: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
e640: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
e650: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
e660: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
e670: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
e680: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
e690: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
e6a0: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
e6b0: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
e6c0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
e6d0: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
e6e0: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
e6f0: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
e700: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
e710: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
e720: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
e730: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
e740: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
e750: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
e760: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
e770: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
e780: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
e790: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
e7a0: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
e7b0: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
e7c0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
e7d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
e7e0: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
e7f0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
e800: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
e810: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
e820: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
e830: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
e840: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
e850: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
e860: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
e870: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
e880: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e890: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
e8a0: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
e8b0: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
e8c0: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
e8d0: 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
e8e0: 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
e8f0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
e900: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
e910: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
e920: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
e930: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e940: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e950: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e960: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
e970: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
e980: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
e990: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e9a0: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
e9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
e9c0: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
e9d0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
e9e0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
e9f0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
ea00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
ea10: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ea20: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
ea30: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
ea40: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
ea50: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
ea60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ea70: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
ea80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ea90: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
eaa0: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
eab0: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
eac0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
ead0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
eae0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
eaf0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
eb00: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
eb10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
eb20: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
eb30: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
eb40: 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
eb50: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
eb60: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
eb70: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
eb80: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
eb90: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
eba0: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
ebb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
ebc0: 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
ebd0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
ebe0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
ebf0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
ec00: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
ec10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
ec20: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
ec30: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
ec40: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
ec50: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ec60: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
ec70: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
ec80: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
ec90: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
eca0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
ecb0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
ecc0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
ecd0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
ece0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
ecf0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
ed00: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
ed10: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
ed20: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
ed30: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
ed40: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
ed50: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
ed60: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
ed70: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
ed80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
ed90: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
eda0: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
edb0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
edc0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
edd0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
ede0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
edf0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ee00: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
ee10: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
ee20: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
ee30: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ee40: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ee50: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
ee60: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
ee70: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
ee80: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
ee90: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
eea0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
eeb0: 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
eec0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
eed0: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
eee0: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
eef0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
ef00: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
ef10: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
ef20: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
ef30: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
ef40: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
ef50: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
ef60: 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
ef70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ef80: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
ef90: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
efa0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
efb0: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
efc0: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
efd0: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
efe0: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
eff0: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
f000: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
f010: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
f020: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
f030: 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
f040: 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
f050: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
f060: 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
f070: 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
f080: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f090: 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
f0a0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
f0b0: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
f0c0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
f0d0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
f0e0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
f0f0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
f100: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
f110: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
f120: 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
f130: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
f140: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
f150: 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
f160: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
f170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
f180: 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
f190: 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
f1a0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f1b0: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
f1c0: 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
f1d0: 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
f1e0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
f1f0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
f200: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
f210: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f220: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
f230: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
f240: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f250: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
f260: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
f270: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
f280: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
f290: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
f2a0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
f2b0: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
f2c0: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
f2d0: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
f2e0: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
f2f0: 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
f300: 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
f310: 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
f320: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
f330: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
f340: 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
f350: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
f360: 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
f370: 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
f380: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
f390: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
f3a0: 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
f3b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
f3c0: 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
f3d0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
f3e0: 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
f3f0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
f400: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
f410: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
f420: 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
f430: 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
f440: 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
f450: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
f460: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
f470: 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
f480: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
f490: 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
f4a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
f4b0: 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
f4c0: 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
f4d0: 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
f4e0: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
f4f0: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
f500: 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
f510: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
f520: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
f530: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
f540: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
f550: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
f560: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
f570: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
f580: 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
f590: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
f5a0: 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
f5b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f5c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f5d0: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
f5e0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f5f0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
f600: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
f610: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
f620: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
f630: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
f640: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
f650: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
f660: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20  implemenation.  
f670: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
f680: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
f690: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
f6a0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
f6b0: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
f6c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f6d0: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
f6e0: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
f6f0: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e  G_PCACHE option.
f700: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
f710: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
f720: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
f730: 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
f740: 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
f750: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
f760: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
f770: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
f780: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
f790: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
f7a0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
f7b0: 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
f7c0: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
f7d0: 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
f7e0: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
f7f0: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
f800: 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
f810: 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
f820: 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
f830: 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
f840: 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
f850: 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
f860: 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
f870: 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
f880: 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
f890: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
f8a0: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
f8b0: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
f8c0: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
f8d0: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
f8e0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
f8f0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
f900: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
f910: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
f920: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
f930: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
f940: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
f950: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
f960: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
f970: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
f980: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
f990: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
f9a0: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
f9b0: 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
f9c0: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
f9d0: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
f9e0: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
f9f0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
fa00: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
fa10: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
fa20: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
fa30: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
fa40: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
fa50: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
fa60: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
fa70: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
fa80: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
fa90: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
faa0: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
fab0: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
fac0: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
fad0: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
fae0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
faf0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
fb00: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
fb10: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
fb20: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
fb30: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
fb40: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
fb50: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
fb60: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
fb70: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
fb80: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
fb90: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
fba0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
fbb0: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
fbc0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
fbd0: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
fbe0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
fbf0: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
fc00: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
fc10: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
fc20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
fc30: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
fc40: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
fc50: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
fc60: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
fc70: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
fc80: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
fc90: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
fca0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
fcb0: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
fcc0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
fcd0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
fce0: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
fcf0: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
fd00: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
fd10: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
fd20: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
fd30: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
fd40: 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
fd50: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
fd60: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
fd70: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
fd80: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
fd90: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
fda0: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
fdb0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
fdc0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
fdd0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
fde0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
fdf0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
fe00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe10: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
fe20: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
fe30: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
fe40: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
fe50: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
fe60: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
fe70: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
fe80: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
fe90: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
fea0: 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
feb0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
fec0: 69 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31  is capped at 2^1
fed0: 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
fee0: 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
fef0: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
ff00: 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20  on size are 2^5 
ff10: 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64  through 2^8.</dd
ff20: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
ff30: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
ff40: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
ff50: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
ff60: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
ff70: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
ff80: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
ff90: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
ffa0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
ffb0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
ffc0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
ffd0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
ffe0: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
fff0: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
10000 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10010 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
10020 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
10030 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
10040 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
10050 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
10060 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
10070 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10080 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10090 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
100a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
100b0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
100c0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
100d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
100e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
100f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10100 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10110 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10120 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
10130 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
10140 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
10150 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
10160 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
10170 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
10180 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10190 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
101a0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
101b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
101c0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
101d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
101e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
101f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10200 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
10210 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10220 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10230 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10250 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
10260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
10270 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
10280 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
10290 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
102a0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
102b0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
102c0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
102d0 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
102e0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
102f0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
10300 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
10310 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
10320 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
10330 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
10340 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
10350 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
10360 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
10370 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
10380 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
10390 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
103a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
103b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
103c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
103d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
103e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
103f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
10400 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
10410 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
10420 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10430 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10440 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
10450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10460 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
10470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10480 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
10490 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
104a0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
104b0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
104c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
104d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
104e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
104f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10500 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
10510 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
10520 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
10530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10540 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
10550 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10560 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
10570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10580 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
10590 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
105a0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
105b0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
105c0 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
105d0 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
105e0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
105f0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
10600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10610 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
10620 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10630 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
10640 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
10650 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
10660 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10670 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
10680 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10690 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
106a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
106b0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
106c0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
106d0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
106e0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
106f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10700 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  IG_PCACHE</dt>.*
10710 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10720 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10730 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10740 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10750 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
10760 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
10770 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
10780 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
10790 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
107a0 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
107b0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
107c0 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
107d0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
107e0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
107f0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
10800 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
10810 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
10820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
10830 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10840 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
10850 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10860 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10870 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10880 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10890 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
108a0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
108b0 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
108c0 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
108d0 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
108e0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
108f0 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
10900 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
10910 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
10920 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
10930 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
10940 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
10950 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
10960 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
10970 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
10980 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
10990 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
109a0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
109b0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
109c0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
109d0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
109e0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
109f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
10a00 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
10a10 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
10a20 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
10a30 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
10a40 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
10a50 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10a60 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
10a70 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
10a80 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
10a90 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
10aa0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
10ab0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
10ac0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
10ad0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
10ae0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
10af0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
10b00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
10b10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10b20 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
10b30 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
10b40 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
10b50 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
10b60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
10b70 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
10b80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
10b90 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
10ba0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
10bb0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
10bc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
10bd0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
10be0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
10bf0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
10c00 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
10c10 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
10c20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
10c30 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
10c40 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
10c50 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
10c60 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
10c70 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
10c80 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
10c90 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
10ca0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
10cb0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
10cc0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
10cd0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
10ce0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10cf0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
10d00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10d10 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
10d20 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
10d30 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
10d40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
10d50 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
10d60 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10d70 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
10d80 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
10d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10da0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
10db0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10dd0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
10de0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
10df0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10e00 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
10e10 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
10e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10e30 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
10e40 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
10e50 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
10e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10e70 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
10e80 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
10e90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
10ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10eb0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
10ec0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
10ed0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10ef0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
10f00 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
10f10 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
10f20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
10f30 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
10f40 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
10f50 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
10f60 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
10f70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10f80 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
10f90 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
10fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10fb0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
10fc0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
10fd0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10fe0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
10ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
11000 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
11010 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11020 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
11030 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
11040 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
11050 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
11060 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
11070 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11080 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
11090 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
110a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
110b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
110c0 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74      14  /* sqlit
110d0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
110e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
110f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
11100 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
11110 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11120 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11130 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11140 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
11150 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
11160 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
11170 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
11180 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
11190 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
111a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
111b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
111c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
111d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
111e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
111f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
11200 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11210 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
11220 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
11230 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
11240 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
11250 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
11260 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
11270 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
11280 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
11290 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
112a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
112b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
112c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
112d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
112e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
112f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
11300 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
11310 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
11320 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
11330 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
11340 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11350 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11360 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11370 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11380 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11390 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
113a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
113b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
113c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
113d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
113e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
113f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11400 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
11410 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
11420 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11430 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
11440 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11450 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
11460 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
11470 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11480 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
11490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
114a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
114b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
114c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
114d0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
114e0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
114f0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
11500 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
11510 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
11520 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
11530 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11540 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
11550 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
11560 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
11570 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
11580 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
11590 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
115a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
115b0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
115c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
115d0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
115e0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
115f0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
11600 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
11610 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11620 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
11630 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
11640 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
11650 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11660 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
11670 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
11680 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
11690 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
116a0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
116b0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
116c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
116d0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
116e0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
116f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11700 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11710 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
11720 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
11730 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
11740 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
11750 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
11760 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
11770 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
11780 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
11790 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
117a0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
117b0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
117c0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
117d0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
117e0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
117f0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
11800 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
11810 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
11820 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
11830 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
11840 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
11850 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
11860 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
11870 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
11880 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
11890 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
118a0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
118b0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
118c0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
118d0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
118e0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
118f0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11900 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
11910 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
11920 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
11930 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
11940 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
11950 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
11960 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11970 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
11980 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
11990 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
119a0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
119b0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
119c0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
119d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
119e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
119f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11a00 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
11a10 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
11a20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
11a30 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
11a40 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
11a50 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
11a60 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
11a70 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
11a80 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
11a90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
11aa0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
11ab0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
11ac0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
11ad0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
11ae0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
11af0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
11b00 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
11b10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
11b20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
11b30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
11b40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
11b50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
11b60 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
11b70 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
11b80 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
11b90 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
11ba0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
11bb0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
11bc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
11bd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
11be0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
11bf0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
11c00 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
11c10 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
11c20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
11c30 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
11c40 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
11c50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
11c60 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
11c70 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
11c80 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
11c90 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
11ca0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
11cb0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
11cc0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
11cd0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
11ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
11cf0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
11d00 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
11d10 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
11d20 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
11d30 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
11d40 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
11d50 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
11d60 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
11d70 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
11d80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
11d90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
11da0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
11db0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
11dc0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
11dd0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
11de0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
11df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
11e00 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11e10 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
11e20 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
11e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11e40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
11e50 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
11e60 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
11e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
11e80 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
11e90 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
11ea0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
11eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
11ec0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
11ed0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
11ee0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
11ef0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
11f00 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
11f10 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
11f20 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
11f30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
11f40 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
11f50 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
11f60 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
11f70 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
11f80 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
11f90 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
11fa0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
11fb0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
11fc0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
11fd0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
11fe0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
11ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
12000 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
12010 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
12020 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
12030 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
12040 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
12050 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
12060 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
12070 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
12080 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
12090 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
120a0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
120b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
120c0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
120d0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
120e0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
120f0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
12100 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
12110 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
12120 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
12130 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
12140 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
12150 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
12160 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
12170 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
12180 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
12190 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
121a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
121b0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
121c0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
121d0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
121e0 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
121f0 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
12200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12210 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
12220 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
12230 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
12240 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
12250 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
12260 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
12270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
12280 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
12290 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
122a0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
122b0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
122c0 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
122d0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
122e0 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
122f0 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
12300 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
12310 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
12320 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
12330 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
12340 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
12350 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12360 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
12370 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
12380 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
12390 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
123a0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
123b0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
123c0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
123d0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
123e0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
123f0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
12400 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
12410 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
12420 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
12430 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
12440 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
12450 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
12460 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
12470 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
12480 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
12490 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
124a0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
124b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
124c0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
124d0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
124e0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
124f0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
12500 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
12510 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
12520 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
12530 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
12540 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
12550 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
12560 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
12570 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
12580 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
12590 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
125a0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
125b0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
125c0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
125d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
125e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
125f0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
12600 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
12610 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
12620 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
12630 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
12640 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
12650 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
12660 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
12670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
12680 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
12690 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
126a0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
126b0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
126c0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
126d0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
126e0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
126f0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
12700 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
12710 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
12720 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
12730 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
12740 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
12750 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
12760 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
12770 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
12780 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12790 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
127a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
127b0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
127c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
127d0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
127e0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
127f0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
12800 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
12810 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
12820 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
12830 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
12840 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
12850 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
12860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12870 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
12880 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
12890 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
128a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
128b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
128c0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
128d0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
128e0 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
128f0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
12900 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
12910 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
12920 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
12930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12940 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
12950 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12960 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
12970 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
12980 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
12990 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
129a0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
129b0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
129c0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
129d0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
129e0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
129f0 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
12a00 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
12a10 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
12a20 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
12a30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
12a40 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
12a50 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
12a60 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
12a70 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
12a80 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
12a90 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
12aa0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
12ab0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
12ac0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
12ad0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
12ae0 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
12af0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
12b00 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
12b10 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
12b20 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
12b30 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
12b40 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
12b50 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
12b60 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
12b70 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
12b80 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
12b90 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
12ba0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
12bb0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
12bc0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
12bd0 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
12be0 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
12bf0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
12c00 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
12c10 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
12c20 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
12c30 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
12c40 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
12c50 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
12c60 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
12c70 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
12c80 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
12c90 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
12ca0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
12cb0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
12cc0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
12cd0 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
12ce0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
12cf0 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
12d00 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
12d10 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
12d20 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
12d30 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
12d40 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
12d50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
12d60 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
12d70 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
12d80 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
12d90 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
12da0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
12db0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
12dc0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
12dd0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
12de0 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
12df0 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
12e00 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
12e10 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
12e20 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
12e30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
12e40 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
12e50 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
12e60 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
12e70 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
12e80 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
12e90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
12ea0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
12eb0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
12ec0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
12ed0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
12ee0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
12ef0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
12f00 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
12f10 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
12f20 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
12f30 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
12f40 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
12f50 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
12f60 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
12f70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
12f80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
12f90 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
12fa0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
12fb0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
12fc0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
12fd0 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
12fe0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
12ff0 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
13000 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
13010 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
13020 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
13030 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
13040 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
13050 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
13060 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
13070 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
13080 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
13090 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
130a0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
130b0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
130c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
130d0 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
130e0 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
130f0 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
13100 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
13110 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
13120 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
13130 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
13140 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
13150 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
13160 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
13170 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
13180 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
13190 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
131a0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
131b0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
131c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
131d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
131e0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
131f0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
13200 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
13210 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
13220 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
13230 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
13240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
13250 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
13260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13270 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
13280 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
13290 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
132a0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
132b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
132c0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
132d0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
132e0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
132f0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
13300 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
13310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
13320 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
13330 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
13340 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
13350 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
13360 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
13370 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
13380 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
13390 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
133a0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
133b0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
133c0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
133d0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
133e0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
133f0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
13400 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
13410 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
13420 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
13430 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
13440 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
13450 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
13460 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
13470 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
13480 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
13490 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
134a0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
134b0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
134c0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
134d0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
134e0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
134f0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
13500 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
13510 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
13520 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
13530 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
13540 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
13550 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
13560 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
13570 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
13580 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
13590 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
135a0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
135b0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
135c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
135d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
135e0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
135f0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
13600 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
13610 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
13620 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
13630 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
13640 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
13650 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
13660 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
13670 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
13680 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
13690 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
136a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
136b0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
136c0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
136d0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
136e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
136f0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
13700 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
13710 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
13720 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
13730 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
13740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
13750 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
13760 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
13770 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
13780 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
13790 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
137a0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
137b0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
137c0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
137d0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
137e0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
137f0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
13800 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
13810 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
13820 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
13830 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
13840 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
13850 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
13860 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
13870 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
13880 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
13890 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
138a0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
138b0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
138c0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
138d0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
138e0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
138f0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
13900 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
13910 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
13920 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
13930 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
13940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13950 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
13960 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
13970 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
13980 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
13990 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
139a0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
139b0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
139c0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
139d0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
139e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
139f0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
13a00 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
13a10 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
13a20 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
13a30 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
13a40 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
13a50 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
13a60 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
13a70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
13a80 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
13a90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
13aa0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
13ab0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
13ac0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
13ad0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
13ae0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
13af0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
13b00 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
13b10 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
13b20 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
13b30 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
13b40 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
13b50 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
13b60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
13b70 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
13b80 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
13b90 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
13ba0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
13bb0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
13bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13bd0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
13be0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
13bf0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
13c00 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
13c10 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
13c20 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
13c30 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
13c40 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
13c50 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
13c60 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
13c70 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
13c80 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
13c90 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
13ca0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
13cb0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
13cc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
13cd0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
13ce0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
13cf0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
13d00 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
13d10 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
13d20 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
13d30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
13d40 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
13d50 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
13d60 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
13d70 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
13d80 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
13d90 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
13da0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
13db0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
13dc0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
13dd0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
13de0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
13df0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
13e00 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
13e10 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
13e20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
13e30 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
13e40 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
13e50 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
13e60 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
13e70 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
13e80 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
13e90 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
13ea0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
13eb0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
13ec0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
13ed0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
13ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13ef0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
13f00 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
13f10 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
13f20 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
13f30 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
13f40 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
13f50 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
13f60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13f70 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
13f80 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
13f90 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
13fa0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
13fb0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
13fc0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
13fd0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13fe0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
13ff0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
14000 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
14010 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
14020 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
14030 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
14040 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
14050 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
14060 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
14070 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
14080 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
14090 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
140a0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
140b0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
140c0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
140d0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
140e0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
140f0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
14100 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
14110 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
14120 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
14130 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
14140 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
14150 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
14160 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
14170 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
14180 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
14190 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
141a0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
141b0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
141c0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
141d0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
141e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
141f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
14200 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
14210 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
14220 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
14230 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
14240 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
14250 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
14260 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
14270 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
14280 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
14290 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
142a0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
142b0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
142c0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
142d0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
142e0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
142f0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
14300 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
14310 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
14320 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
14330 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
14340 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
14350 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
14360 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
14370 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
14380 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
14390 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
143a0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
143b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
143c0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
143d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
143e0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
143f0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
14400 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
14410 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
14420 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
14430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
14440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
14450 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
14460 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
14470 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
14480 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
14490 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
144a0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
144b0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
144c0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
144d0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
144e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
144f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
14500 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
14510 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
14520 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
14530 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
14540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14550 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
14560 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
14570 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
14580 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
14590 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
145a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
145b0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
145c0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
145d0 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
145e0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
145f0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
14600 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
14610 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
14620 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
14630 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
14640 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
14650 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
14660 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
14670 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
14680 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
14690 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
146a0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
146b0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
146c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
146d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
146e0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
146f0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
14700 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
14710 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
14720 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
14730 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14740 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
14750 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
14760 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
14770 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
14780 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
14790 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
147a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
147b0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
147c0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
147d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
147e0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
147f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
14800 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
14810 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
14820 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14830 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
14840 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
14850 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
14860 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
14870 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
14880 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
14890 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
148a0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
148b0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
148c0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
148d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
148e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
148f0 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
14900 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
14910 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
14920 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
14930 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
14940 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
14950 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
14960 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
14970 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
14980 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
14990 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
149a0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
149b0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
149c0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
149d0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
149e0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
149f0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
14a00 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
14a10 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
14a20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
14a30 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
14a40 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
14a50 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
14a60 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
14a70 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
14a80 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
14a90 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
14aa0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
14ab0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
14ac0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
14ad0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
14ae0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
14af0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
14b00 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
14b10 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
14b20 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
14b30 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
14b40 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
14b50 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
14b60 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
14b70 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
14b80 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
14b90 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
14ba0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
14bb0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
14bc0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
14bd0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
14be0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
14bf0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
14c00 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
14c10 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
14c20 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
14c30 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
14c40 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
14c50 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
14c60 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
14c70 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
14c80 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
14c90 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
14ca0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
14cb0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
14cc0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
14cd0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
14ce0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
14cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
14d00 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
14d10 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
14d20 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
14d30 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
14d40 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
14d50 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14d60 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
14d70 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
14d80 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
14d90 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
14da0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
14db0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
14dc0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
14dd0 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
14de0 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
14df0 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
14e00 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
14e10 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
14e20 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
14e30 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
14e40 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
14e50 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
14e60 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
14e70 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
14e80 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
14e90 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
14ea0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
14eb0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
14ec0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
14ed0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
14ee0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
14ef0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
14f00 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
14f10 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
14f20 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
14f30 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
14f40 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
14f50 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
14f60 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
14f70 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
14f80 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14f90 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
14fa0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
14fb0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
14fc0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
14fd0 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
14fe0 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
14ff0 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
15000 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
15010 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
15020 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
15030 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
15040 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
15050 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
15060 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
15070 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
15080 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
15090 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
150a0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
150b0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
150c0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
150d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
150e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
150f0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
15100 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
15110 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
15120 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
15130 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
15140 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
15150 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
15160 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
15170 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
15180 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
15190 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
151a0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
151b0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
151c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
151d0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
151e0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
151f0 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
15200 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
15210 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
15220 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
15230 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
15240 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
15250 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15260 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
15270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
15280 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
15290 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
152a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
152b0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
152c0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
152d0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
152e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
152f0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
15300 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
15310 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
15320 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
15330 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
15340 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
15350 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
15360 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
15370 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
15380 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
15390 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
153a0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
153b0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
153c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
153d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
153e0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
153f0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
15400 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
15410 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
15420 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
15430 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
15440 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
15450 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
15460 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
15470 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
15480 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15490 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
154a0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
154b0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
154c0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
154d0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
154e0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
154f0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
15500 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
15510 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
15520 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
15530 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
15540 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15550 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
15560 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
15570 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
15580 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
15590 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
155a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
155b0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
155c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
155d0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
155e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
155f0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
15600 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
15610 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
15620 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
15630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15640 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
15650 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
15660 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
15670 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
15680 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
15690 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
156a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
156b0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
156c0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
156d0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
156e0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
156f0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
15700 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
15710 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
15720 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
15730 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
15740 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
15750 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
15760 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
15770 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
15780 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
15790 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
157a0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
157b0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
157c0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
157d0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
157e0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
157f0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
15800 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
15810 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
15820 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
15830 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
15840 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
15850 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
15860 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
15870 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
15880 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
15890 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
158a0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
158b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
158c0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
158d0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
158e0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
158f0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
15900 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
15910 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
15920 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
15930 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
15940 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
15950 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
15960 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
15970 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
15980 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
15990 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
159a0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
159b0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
159c0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
159d0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
159e0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
159f0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
15a00 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
15a10 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
15a20 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
15a30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15a40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
15a50 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
15a60 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
15a70 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
15a80 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
15a90 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
15aa0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
15ab0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
15ac0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
15ad0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
15ae0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
15af0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
15b00 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
15b10 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
15b20 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
15b30 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
15b40 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
15b50 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
15b60 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
15b70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15b80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
15b90 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
15ba0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
15bb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15bc0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
15bd0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
15be0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
15bf0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
15c00 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
15c10 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
15c20 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15c30 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
15c40 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
15c50 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
15c60 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
15c70 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
15c80 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
15c90 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
15ca0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
15cb0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
15cc0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
15cd0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
15ce0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
15cf0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
15d00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15d10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15d20 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
15d30 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15d40 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
15d50 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
15d60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
15d70 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
15d80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15d90 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
15da0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15db0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
15dc0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15dd0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
15de0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
15df0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
15e00 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
15e10 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
15e20 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
15e30 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
15e40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
15e50 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15e60 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
15e70 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
15e80 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
15e90 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
15ea0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
15eb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
15ec0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
15ed0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
15ee0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
15ef0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
15f00 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
15f10 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
15f20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
15f30 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
15f40 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
15f50 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
15f60 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
15f70 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
15f80 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
15f90 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
15fa0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
15fb0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
15fc0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
15fd0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
15fe0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
15ff0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
16000 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
16010 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16020 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
16030 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
16040 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
16050 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
16060 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
16070 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
16080 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
16090 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
160a0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
160b0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
160c0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
160d0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
160e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
160f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
16100 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
16110 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
16120 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
16130 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
16140 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
16150 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
16160 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
16170 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
16180 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
16190 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
161a0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
161b0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
161c0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
161d0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
161e0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
161f0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
16200 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
16210 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
16220 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
16230 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
16240 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
16250 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
16260 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
16270 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
16280 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
16290 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
162a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
162b0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
162c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
162d0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
162e0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
162f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
16300 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
16310 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
16320 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
16330 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
16340 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
16350 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
16360 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
16370 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
16380 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
16390 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
163a0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
163b0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
163c0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
163d0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
163e0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
163f0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
16400 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
16410 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
16420 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
16430 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16440 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
16450 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
16460 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
16470 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
16480 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
16490 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
164a0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
164b0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
164c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
164d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
164e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
164f0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
16500 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
16510 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
16520 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
16530 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
16540 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16550 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
16560 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
16570 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
16580 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
16590 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
165a0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
165b0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
165c0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
165d0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
165e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
165f0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
16600 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
16610 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
16620 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
16630 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
16640 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
16650 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
16660 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
16670 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
16680 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
16690 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
166a0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
166b0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
166c0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
166d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
166e0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
166f0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
16700 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
16710 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
16720 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
16730 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
16740 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
16750 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
16760 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
16770 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
16780 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
16790 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
167a0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
167b0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
167c0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
167d0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
167e0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
167f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16800 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
16810 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
16820 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
16830 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
16840 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
16850 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
16860 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
16870 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
16880 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
16890 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
168a0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
168b0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
168c0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
168d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
168e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
168f0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
16900 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
16910 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
16920 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
16930 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
16940 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
16950 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
16960 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
16970 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
16980 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
16990 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
169a0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
169b0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
169c0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
169d0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
169e0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
169f0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
16a00 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
16a10 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
16a20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
16a30 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
16a40 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
16a50 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
16a60 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
16a70 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
16a80 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
16a90 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
16aa0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
16ab0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
16ac0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
16ad0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
16ae0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
16af0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
16b00 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
16b10 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
16b20 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
16b30 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
16b40 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
16b50 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
16b60 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
16b70 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
16b80 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
16b90 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
16ba0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
16bb0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
16bc0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
16bd0 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
16be0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
16bf0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
16c00 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
16c10 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
16c20 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
16c30 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
16c40 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
16c50 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
16c60 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
16c70 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
16c80 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
16c90 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
16ca0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
16cb0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
16cc0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
16cd0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
16ce0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
16cf0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
16d00 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
16d10 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
16d20 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16d30 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
16d40 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
16d50 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
16d60 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16d70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
16d80 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
16d90 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
16da0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
16db0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
16dc0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
16dd0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
16de0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16df0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
16e00 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
16e10 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16e20 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16e30 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16e40 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16e50 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16e60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16e70 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
16e80 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
16e90 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
16ea0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
16eb0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
16ec0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
16ed0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
16ee0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
16ef0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16f00 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
16f10 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
16f20 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
16f30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16f40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
16f50 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
16f60 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
16f70 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
16f80 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
16f90 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
16fa0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
16fb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16fc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
16fd0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
16fe0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
16ff0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
17000 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
17010 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
17020 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
17030 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
17040 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
17050 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
17060 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
17070 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
17080 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
17090 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
170a0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
170b0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
170c0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
170d0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
170e0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
170f0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
17100 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
17110 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
17120 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
17130 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
17140 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
17150 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
17160 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
17170 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
17180 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
17190 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
171a0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
171b0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
171c0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
171d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
171e0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
171f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
17200 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
17210 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
17220 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
17230 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
17240 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
17250 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
17260 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
17270 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
17280 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
17290 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
172a0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
172b0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
172c0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
172d0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
172e0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
172f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
17300 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
17310 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
17320 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
17330 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
17340 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
17350 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
17360 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
17370 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
17380 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
17390 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
173a0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
173b0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
173c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
173d0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
173e0 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
173f0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
17400 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
17410 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
17420 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
17430 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
17440 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
17450 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
17460 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
17470 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
17480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17490 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
174a0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
174b0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
174c0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
174d0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
174e0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
174f0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
17500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17510 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
17520 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
17530 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
17540 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
17550 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
17560 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
17570 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
17580 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
17590 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
175a0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
175b0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
175c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
175d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
175e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
175f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
17600 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
17610 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
17620 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
17630 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
17640 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
17650 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17660 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
17670 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
17680 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
17690 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
176a0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
176b0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
176c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
176d0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
176e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
176f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
17700 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
17710 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
17720 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
17730 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
17740 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
17750 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
17760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17770 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
17780 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
17790 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
177a0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
177b0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
177c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
177d0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
177e0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
177f0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
17800 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
17810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
17820 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
17830 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
17840 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
17850 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
17860 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
17870 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
17880 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
17890 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
178a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
178b0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
178c0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
178d0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
178e0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
178f0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
17900 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
17910 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
17920 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
17930 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
17940 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
17950 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
17960 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
17970 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
17980 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
17990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
179a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
179b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
179c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
179d0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
179e0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
179f0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
17a00 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
17a10 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17a20 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
17a30 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
17a40 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
17a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
17a60 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
17a70 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
17a80 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
17a90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17aa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
17ab0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
17ac0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
17ad0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
17ae0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
17af0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
17b00 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
17b10 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
17b20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17b30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
17b40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
17b50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17b60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b70 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
17b80 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
17b90 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
17ba0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
17bb0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
17bc0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
17bd0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
17be0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17bf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17c00 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
17c10 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
17c20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
17c30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17c40 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
17c50 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
17c60 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
17c70 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
17c80 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
17c90 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
17ca0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
17cb0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
17cc0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
17cd0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
17ce0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
17cf0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
17d00 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
17d10 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
17d20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17d30 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
17d40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
17d50 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
17d60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
17d70 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
17d80 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
17d90 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
17da0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
17db0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
17dc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
17dd0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
17de0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
17df0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
17e00 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
17e10 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
17e20 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
17e30 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
17e40 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
17e50 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
17e60 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
17e70 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
17e80 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
17e90 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
17ea0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
17eb0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
17ec0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
17ed0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
17ee0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
17ef0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
17f00 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
17f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
17f20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
17f30 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
17f40 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
17f50 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
17f60 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
17f70 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
17f80 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
17f90 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
17fa0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
17fb0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
17fc0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
17fd0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
17fe0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
17ff0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
18000 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
18010 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
18020 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
18030 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
18040 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
18050 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
18060 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
18070 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
18080 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
18090 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
180a0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
180b0 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
180c0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
180d0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
180e0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
180f0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
18100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
18110 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
18120 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
18130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
18140 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
18150 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
18160 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
18170 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
18180 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
18190 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
181a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
181b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
181c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
181d0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
181e0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
181f0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
18200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
18210 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
18220 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
18230 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
18240 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
18250 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
18260 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
18270 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
18280 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18290 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
182a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
182b0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
182c0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
182d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
182e0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
182f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18300 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
18310 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
18320 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
18330 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
18340 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
18350 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
18360 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
18370 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
18380 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18390 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
183a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
183b0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
183c0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
183d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
183e0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
183f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
18400 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18410 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
18420 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
18430 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
18440 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
18450 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
18460 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
18470 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
18480 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
18490 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
184a0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
184b0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
184c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
184d0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
184e0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
184f0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
18500 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
18510 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
18520 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
18530 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
18540 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
18550 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
18560 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
18570 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
18580 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
18590 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
185a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
185b0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
185c0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
185d0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
185e0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
185f0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
18600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
18610 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
18620 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
18630 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
18640 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
18650 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
18660 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
18670 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
18680 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
18690 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
186a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
186b0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
186c0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
186d0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
186e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
186f0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
18700 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
18710 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
18720 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
18730 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
18740 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
18750 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
18760 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
18770 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
18780 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
18790 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
187a0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
187b0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
187c0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
187d0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
187e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
187f0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
18800 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
18810 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
18820 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
18830 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
18840 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
18850 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
18860 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
18870 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
18880 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
18890 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
188a0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
188b0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
188c0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
188d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
188e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
188f0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
18900 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
18910 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
18920 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
18930 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
18940 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
18950 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
18960 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
18970 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
18980 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
18990 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
189a0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
189b0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
189c0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
189d0 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
189e0 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
189f0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
18a00 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
18a10 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
18a20 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
18a30 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
18a40 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
18a50 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
18a60 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
18a70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
18a80 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
18a90 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
18aa0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
18ab0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18ac0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
18ad0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
18ae0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
18af0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
18b00 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
18b10 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
18b20 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
18b30 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
18b40 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18b50 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
18b60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18b70 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
18b80 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
18b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
18ba0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
18bb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
18bc0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
18bd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
18be0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
18bf0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
18c00 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
18c10 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
18c20 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
18c30 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
18c40 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
18c50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18c60 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
18c70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
18c80 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
18c90 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
18ca0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
18cb0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
18cc0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
18cd0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
18ce0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
18cf0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
18d00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
18d10 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
18d20 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
18d30 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
18d40 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
18d50 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
18d60 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
18d70 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
18d80 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
18d90 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
18da0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
18db0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
18dc0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
18dd0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
18de0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
18df0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
18e00 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
18e10 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
18e20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
18e30 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
18e40 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
18e50 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
18e60 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
18e70 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
18e80 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
18e90 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
18ea0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
18eb0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
18ec0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
18ed0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
18ee0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
18ef0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
18f00 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
18f10 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
18f20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
18f30 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
18f40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18f50 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
18f60 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
18f70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
18f80 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
18f90 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
18fa0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
18fb0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
18fc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18fd0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
18fe0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
18ff0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
19000 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
19010 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
19020 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
19030 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
19040 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
19050 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
19060 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19070 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19080 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19090 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
190a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
190b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
190c0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
190d0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
190e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
190f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
19100 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
19110 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
19120 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
19130 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
19140 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
19150 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
19160 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
19170 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
19180 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
19190 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
191a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
191b0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
191c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
191d0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
191e0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
191f0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
19200 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
19210 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
19220 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
19230 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19240 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
19250 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
19260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19270 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
19280 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
19290 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
192a0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
192b0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
192c0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
192d0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
192e0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
192f0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
19300 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
19310 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
19320 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
19330 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
19340 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
19350 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
19360 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
19370 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
19380 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
19390 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
193a0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
193b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
193c0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
193d0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
193e0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
193f0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
19400 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
19410 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
19420 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
19430 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
19440 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
19450 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
19460 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
19470 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
19480 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
19490 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
194a0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
194b0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
194c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
194d0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
194e0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
194f0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
19500 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
19510 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
19520 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
19530 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
19540 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
19550 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
19560 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
19570 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
19580 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
19590 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
195a0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
195b0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
195c0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
195d0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
195e0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
195f0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
19600 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
19610 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
19620 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
19630 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
19640 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
19650 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
19660 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
19670 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
19680 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
19690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
196a0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
196b0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
196c0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
196d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
196e0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
196f0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
19700 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
19710 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
19720 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
19730 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
19740 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
19750 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
19760 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
19770 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
19780 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
19790 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
197a0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
197b0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
197c0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
197d0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
197e0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
197f0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
19800 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
19810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19820 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
19830 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
19840 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19850 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
19860 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
19870 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
19880 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
19890 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
198a0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
198b0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
198c0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
198d0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
198e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
198f0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
19900 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
19910 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
19920 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19930 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
19940 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
19950 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
19960 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
19970 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
19990 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
199a0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
199b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
199c0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
199d0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
199e0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
199f0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
19a00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19a10 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
19a20 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
19a30 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
19a40 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
19a50 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
19a60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19a70 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
19a80 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
19a90 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
19aa0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
19ab0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
19ac0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
19ad0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
19ae0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
19af0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
19b00 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
19b10 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
19b20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19b30 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
19b40 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
19b50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
19b60 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
19b70 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
19b80 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
19b90 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
19ba0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
19bb0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
19bc0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
19bd0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
19be0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
19bf0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
19c00 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
19c10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19c20 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
19c30 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
19c40 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
19c50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19c60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
19c70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
19c80 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
19c90 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
19ca0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
19cb0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
19cc0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
19cd0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
19ce0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
19cf0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
19d00 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
19d10 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
19d20 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
19d30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
19d40 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
19d50 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
19d60 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
19d70 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
19d80 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
19d90 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
19da0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
19db0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
19dc0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
19dd0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
19de0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19df0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
19e00 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
19e10 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
19e20 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
19e30 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
19e40 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
19e50 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
19e60 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
19e70 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
19e80 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
19e90 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
19ea0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
19eb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19ec0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
19ed0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
19ee0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
19ef0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
19f00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
19f10 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
19f20 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
19f30 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
19f40 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
19f50 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
19f60 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
19f70 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
19f80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19f90 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
19fa0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
19fb0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
19fc0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
19fd0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
19fe0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
19ff0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1a000 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1a010 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1a020 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1a030 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1a040 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1a050 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1a060 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1a070 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1a080 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1a090 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1a0a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a0b0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1a0c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1a0d0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1a0e0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1a0f0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1a100 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1a110 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1a120 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1a130 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1a140 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1a150 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1a160 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1a170 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1a180 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1a190 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1a1a0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1a1b0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1a1c0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1a1d0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1a1e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a1f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1a200 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1a210 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1a220 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1a230 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1a240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a250 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a260 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1a270 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1a280 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1a290 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1a2a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1a2b0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1a2c0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1a2d0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1a2e0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1a2f0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1a300 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1a310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a330 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1a340 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1a350 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1a360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a370 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1a380 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1a390 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1a3a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1a3b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a3c0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1a3d0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1a3e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1a3f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a400 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a410 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1a420 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1a430 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1a440 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1a450 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1a460 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1a470 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1a480 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a490 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a4a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1a4b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1a4c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1a4d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1a4e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a4f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1a500 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1a510 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1a520 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a540 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1a550 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1a560 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1a570 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a590 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1a5a0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1a5b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1a5c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a5d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a5e0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1a5f0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1a600 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a610 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a630 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1a640 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1a650 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1a660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a680 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1a690 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1a6a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a6b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a6c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a6d0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1a6e0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1a6f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1a700 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a720 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1a730 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1a740 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1a750 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a770 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1a780 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1a790 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1a7a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a7b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a7c0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1a7d0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1a7e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1a7f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1a810 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1a820 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1a830 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1a840 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1a850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1a860 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1a870 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1a880 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1a890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a8a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1a8b0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1a8c0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1a8d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1a8e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a8f0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1a900 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1a910 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1a920 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1a930 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1a940 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1a950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1a960 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1a970 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1a980 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1a990 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1a9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1a9b0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1a9c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1a9d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a9e0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1a9f0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1aa00 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1aa10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aa20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aa30 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1aa40 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1aa50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1aa60 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1aa70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1aa80 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1aa90 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1aaa0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1aab0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1aac0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1aad0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1aae0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1aaf0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1ab00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ab10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ab20 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1ab30 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1ab40 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1ab50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ab60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ab70 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1ab80 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1ab90 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1aba0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1abb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1abc0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1abd0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1abe0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1abf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ac00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ac10 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1ac20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1ac30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1ac40 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1ac50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ac60 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1ac70 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1ac80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1ac90 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1aca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1acb0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1acc0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1acd0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1ace0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1acf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1ad00 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1ad10 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1ad20 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1ad30 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1ad40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1ad50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1ad60 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1ad70 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1ad80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1ad90 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1ada0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1adb0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1adc0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1add0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1ade0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1adf0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1ae00 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1ae10 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1ae20 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1ae30 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1ae40 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1ae50 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1ae60 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1ae70 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1ae80 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1ae90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1aea0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1aeb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1aec0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1aed0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1aee0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1aef0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1af00 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1af10 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1af20 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1af30 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1af40 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1af50 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1af60 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1af70 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1af80 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1af90 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1afa0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1afb0 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1afc0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1afd0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1afe0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1aff0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1b000 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1b010 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b020 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1b030 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1b040 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1b050 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1b060 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1b070 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1b080 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1b090 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1b0a0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1b0b0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1b0c0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1b0d0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1b0e0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1b0f0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1b100 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1b110 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1b120 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1b130 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1b140 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1b150 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1b160 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1b170 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1b180 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1b190 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1b1a0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1b1b0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1b1c0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1b1d0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1b1e0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1b1f0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1b200 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1b210 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1b220 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1b230 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1b240 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1b250 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1b260 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1b270 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1b280 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1b290 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1b2a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1b2b0 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1b2c0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1b2d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1b2e0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1b2f0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1b300 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1b310 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1b320 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1b330 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1b340 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1b350 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1b360 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1b370 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1b380 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1b390 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1b3a0 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1b3b0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1b3c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1b3d0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1b3e0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1b3f0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1b400 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1b410 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1b420 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1b430 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1b440 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b450 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1b460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1b470 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1b480 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1b490 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1b4a0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1b4b0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1b4c0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1b4d0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1b4e0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1b4f0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1b500 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1b510 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b520 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1b530 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1b540 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1b550 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1b560 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1b570 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1b580 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1b590 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1b5a0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1b5b0 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1b5c0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1b5d0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1b5e0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1b5f0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1b600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b610 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1b620 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1b630 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1b640 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1b650 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1b660 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1b670 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1b680 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1b690 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1b6a0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1b6b0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1b6c0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1b6d0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1b6e0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1b6f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b700 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1b710 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1b720 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1b730 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1b740 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1b750 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1b760 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1b770 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1b780 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1b790 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1b7a0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1b7b0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1b7c0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1b7d0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1b7e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1b7f0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1b800 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1b810 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1b820 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b830 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1b840 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1b850 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1b860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1b870 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1b880 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1b890 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1b8a0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1b8b0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1b8c0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1b8d0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1b8e0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1b8f0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1b900 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1b910 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1b920 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b930 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1b940 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1b950 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
1b960 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
1b970 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1b980 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
1b990 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1b9a0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1b9b0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1b9c0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1b9d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1b9e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1b9f0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1ba00 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1ba10 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
1ba20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ba30 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1ba40 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1ba50 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1ba60 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1ba70 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1ba80 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1ba90 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1baa0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1bab0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1bac0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1bad0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1bae0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1baf0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1bb00 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1bb10 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1bb20 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1bb30 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1bb40 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1bb50 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1bb60 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1bb70 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1bb80 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1bb90 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1bba0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1bbb0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1bbc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1bbd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1bbe0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1bbf0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1bc00 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1bc10 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1bc20 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1bc30 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1bc40 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1bc50 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1bc60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1bc70 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1bc80 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1bc90 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1bca0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1bcb0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1bcc0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1bcd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1bce0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1bcf0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1bd00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1bd10 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1bd20 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1bd30 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1bd40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1bd50 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1bd60 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1bd70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1bd80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1bd90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1bda0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1bdb0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1bdc0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1bdd0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1bde0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1bdf0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1be00 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1be10 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1be20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1be30 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1be40 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1be50 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1be60 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1be70 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1be80 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1be90 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1bea0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1beb0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1bec0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1bed0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1bee0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1bef0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1bf00 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1bf10 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1bf20 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1bf30 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1bf40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1bf50 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1bf60 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1bf70 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53  E],.** and/or [S
1bf80 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1bf90 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29  TECACHE] flags:)
1bfa0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1bfb0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1bfc0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1bfd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1bfe0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1bff0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1c000 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1c010 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1c020 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1c030 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1c040 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1c050 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1c060 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1c070 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c080 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c090 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1c0a0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1c0b0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1c0c0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1c0d0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1c0e0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1c0f0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1c100 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1c110 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1c120 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1c130 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1c140 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1c150 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1c160 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1c170 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c180 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1c190 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1c1a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1c1b0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1c1c0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1c1d0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1c1e0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
1c1f0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1c200 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1c210 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1c220 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1c230 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1c240 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1c250 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1c260 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1c270 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1c280 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c290 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1c2a0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1c2b0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1c2c0 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
1c2d0 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
1c2e0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
1c2f0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
1c300 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1c310 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
1c320 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1c330 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  X],.** [SQLITE_O
1c340 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1c350 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1c360 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1c370 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65  E] flags,.** the
1c380 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1c390 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1c3a0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1c3b0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1c3c0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1c3d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1c3e0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1c3f0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1c400 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1c410 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1c420 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1c430 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1c440 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1c450 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1c460 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1c470 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1c480 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1c490 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1c4a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1c4b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1c4c0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1c4d0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1c4e0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1c4f0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1c500 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1c510 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1c520 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1c530 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1c540 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1c550 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1c560 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1c570 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1c580 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1c590 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1c5a0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1c5b0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1c5c0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1c5d0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1c5e0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1c5f0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1c600 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1c610 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1c620 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1c630 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1c640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c650 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1c660 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1c670 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1c680 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1c690 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  led..**.** ^If t
1c6a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1c6b0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1c6c0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1c6d0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1c6e0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1c6f0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1c700 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
1c710 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1c720 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1c730 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1c740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c750 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1c760 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1c770 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1c780 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1c790 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1c7a0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1c7b0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1c7c0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1c7d0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1c7e0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1c7f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1c800 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1c810 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1c820 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1c830 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1c840 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1c850 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1c860 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1c870 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1c880 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1c890 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1c8a0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1c8b0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1c8c0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1c8d0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1c8e0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
1c8f0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
1c900 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
1c910 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
1c920 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
1c930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c940 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
1c950 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1c960 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1c970 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1c980 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1c990 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1c9a0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1c9b0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1c9c0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1c9d0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1c9e0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1c9f0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1ca00 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1ca10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1ca20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1ca30 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1ca40 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1ca50 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1ca60 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1ca70 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1ca80 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1ca90 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1caa0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1cab0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1cac0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1cad0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1cae0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1caf0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1cb00 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1cb10 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1cb20 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1cb30 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1cb40 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1cb50 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1cb60 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1cb70 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1cb80 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1cb90 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1cba0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
1cbb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1cbc0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
1cbd0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1cbe0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1cbf0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1cc00 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1cc10 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1cc20 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1cc30 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1cc40 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
1cc50 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
1cc60 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1cc70 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
1cc80 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1cc90 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1cca0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1ccb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1ccc0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
1ccd0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
1cce0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1ccf0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1cd00 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1cd10 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
1cd20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1cd30 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1cd40 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
1cd50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1cd60 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
1cd70 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
1cd80 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
1cd90 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
1cda0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1cdb0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
1cdc0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
1cdd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cde0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1cdf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1ce00 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1ce10 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1ce20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1ce30 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1ce40 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1ce50 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1ce60 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1ce70 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1ce80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1ce90 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1cea0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1ceb0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1cec0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1ced0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1cee0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1cef0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1cf00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1cf10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1cf20 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
1cf30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1cf40 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
1cf50 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
1cf60 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
1cf70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1cf80 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
1cf90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1cfa0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
1cfb0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1cfc0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1cfd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1cfe0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1cff0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1d000 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1d010 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1d020 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1d030 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1d040 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
1d050 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
1d060 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1d070 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1d080 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1d090 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1d0a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1d0b0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1d0c0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1d0d0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1d0e0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1d0f0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1d100 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1d110 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1d120 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1d130 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1d140 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1d150 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
1d160 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1d170 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
1d180 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
1d190 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
1d1a0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
1d1b0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
1d1c0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1d1d0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
1d1e0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
1d1f0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
1d200 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
1d210 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1d220 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
1d230 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
1d240 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
1d250 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
1d260 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
1d270 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
1d280 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
1d290 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
1d2a0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
1d2b0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
1d2c0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
1d2d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1d2e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
1d2f0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
1d300 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
1d310 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1d320 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
1d330 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
1d340 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
1d350 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1d360 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
1d370 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
1d380 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
1d390 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
1d3a0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
1d3b0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
1d3c0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1d3d0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1d3e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1d3f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1d400 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1d410 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1d420 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1d430 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1d440 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1d450 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1d460 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1d470 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
1d480 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1d490 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1d4a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1d4b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1d4c0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1d4d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1d4e0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1d4f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1d500 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1d510 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1d520 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1d530 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1d540 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1d550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1d560 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1d570 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1d580 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1d590 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1d5a0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1d5b0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1d5c0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1d5d0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1d5e0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1d5f0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1d600 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1d610 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1d620 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1d630 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1d640 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1d650 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1d660 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1d670 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1d680 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1d690 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1d6a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d6b0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1d6c0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1d6d0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1d6e0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1d6f0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1d700 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1d710 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1d720 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1d730 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1d740 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1d750 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1d760 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1d770 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1d780 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1d790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1d7a0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1d7b0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1d7c0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1d7d0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1d7e0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1d7f0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1d800 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1d810 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1d820 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1d830 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1d840 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1d850 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1d860 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1d870 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1d880 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1d890 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1d8a0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1d8b0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1d8c0 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
1d8d0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1d8e0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1d8f0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1d900 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1d910 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1d920 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1d930 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1d940 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1d950 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1d960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1d970 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1d980 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1d990 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1d9a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1d9b0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1d9c0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1d9d0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1d9e0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1d9f0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1da00 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1da10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1da20 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1da30 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1da40 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1da50 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1da60 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1da70 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1da80 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1da90 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
1daa0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
1dab0 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
1dac0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
1dad0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
1dae0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
1daf0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1db00 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
1db10 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
1db20 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
1db30 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
1db40 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
1db50 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1db60 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1db70 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
1db80 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
1db90 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1dba0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1dbb0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1dbc0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1dbd0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1dbe0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
1dbf0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
1dc00 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1dc10 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
1dc20 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
1dc30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
1dc40 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
1dc50 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
1dc60 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
1dc70 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
1dc80 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
1dc90 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
1dca0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
1dcb0 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
1dcc0 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
1dcd0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
1dce0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
1dcf0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
1dd00 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1dd10 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1dd20 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1dd30 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1dd40 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1dd50 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1dd60 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1dd70 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1dd80 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1dd90 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1dda0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ddb0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1ddc0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1ddd0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1dde0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1ddf0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1de00 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1de10 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1de20 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1de30 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1de40 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1de50 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1de60 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1de70 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1de80 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1de90 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1dea0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1deb0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1dec0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1ded0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1dee0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1def0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1df00 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1df10 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1df20 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1df30 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1df40 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1df50 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1df60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1df70 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1df80 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1df90 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1dfa0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1dfb0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1dfc0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1dfd0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1dfe0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1dff0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1e000 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1e010 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1e020 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1e030 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1e040 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1e050 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1e060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1e070 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1e080 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1e090 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1e0a0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1e0b0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
1e0c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1e0d0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
1e0e0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1e0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1e100 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1e110 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1e120 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1e130 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1e140 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1e150 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1e160 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1e170 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1e180 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1e190 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1e1a0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1e1b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1e1c0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1e1d0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1e1e0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1e1f0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1e200 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e210 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1e220 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e230 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1e240 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1e250 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
1e260 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
1e270 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1e280 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1e290 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e2a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e2b0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1e2c0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
1e2d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e2e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1e2f0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1e300 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e310 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1e320 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1e330 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1e340 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1e350 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
1e360 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e370 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1e380 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1e390 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1e3a0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1e3b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1e3c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e3d0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1e3e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e3f0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1e400 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1e410 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1e420 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1e430 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1e440 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1e450 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1e460 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1e470 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1e480 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1e490 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
1e4a0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e4b0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1e4c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1e4d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1e4e0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1e4f0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1e500 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1e510 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1e520 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1e530 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
1e540 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
1e550 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
1e560 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
1e570 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
1e580 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
1e590 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
1e5a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1e5b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1e5c0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
1e5d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e5e0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1e5f0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
1e600 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
1e610 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e620 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
1e630 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e640 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
1e650 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
1e660 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
1e670 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  dd>.**.** ^(<dt>
1e680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1e690 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1e6a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e6b0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1e6c0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1e6d0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
1e6e0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
1e6f0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
1e700 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1e710 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
1e720 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
1e730 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1e740 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
1e750 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
1e760 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
1e770 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
1e780 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e790 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1e7a0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1e7b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1e7c0 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
1e7d0 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
1e7e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
1e7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e800 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1e810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1e820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e830 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1e840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e850 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1e860 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1e870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e880 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1e890 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1e8a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1e8b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1e8c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1e8d0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1e8e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1e8f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1e900 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1e910 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1e920 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1e930 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1e940 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1e950 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1e960 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1e970 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1e980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1e990 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1e9a0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1e9b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1e9c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1e9d0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
1e9e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
1e9f0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
1ea00 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
1ea10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1ea20 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
1ea30 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
1ea40 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1ea50 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1ea60 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1ea70 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1ea80 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1ea90 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1eaa0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1eab0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1eac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1ead0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1eae0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1eaf0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1eb00 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1eb10 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1eb20 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
1eb30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
1eb40 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1eb50 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
1eb60 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
1eb70 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
1eb80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
1eb90 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
1eba0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
1ebb0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1ebc0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
1ebd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
1ebe0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
1ebf0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
1ec00 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ec10 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
1ec20 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
1ec30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ec40 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
1ec50 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
1ec60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1ec70 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
1ec80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
1ec90 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
1eca0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
1ecb0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1ecc0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1ecd0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1ece0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1ecf0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1ed00 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
1ed10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1ed20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
1ed30 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
1ed40 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
1ed50 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
1ed60 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1ed70 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1ed80 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1ed90 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1eda0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1edb0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1edc0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
1edd0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
1ede0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
1edf0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
1ee00 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
1ee10 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
1ee20 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
1ee30 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
1ee40 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
1ee50 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
1ee60 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
1ee70 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
1ee80 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
1ee90 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
1eea0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
1eeb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
1eec0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
1eed0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
1eee0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1eef0 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  r bytes..**.** ^
1ef00 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
1ef10 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
1ef20 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1ef30 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
1ef40 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
1ef50 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
1ef60 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
1ef70 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
1ef80 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
1ef90 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
1efa0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
1efb0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
1efc0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
1efd0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
1efe0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
1eff0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
1f000 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1f010 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1f020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f030 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1f040 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1f050 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1f060 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
1f070 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1f080 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1f090 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
1f0a0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1f0b0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
1f0c0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
1f0d0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
1f0e0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
1f0f0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
1f100 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
1f110 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
1f120 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
1f130 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
1f140 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
1f150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
1f160 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1f170 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
1f180 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
1f190 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
1f1a0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
1f1b0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
1f1c0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
1f1d0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
1f1e0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
1f1f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1f200 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
1f210 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1f220 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1f230 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1f240 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1f250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f260 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1f270 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1f280 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1f290 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1f2a0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1f2b0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1f2c0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1f2d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1f2e0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1f2f0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1f300 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
1f310 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
1f320 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f330 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
1f340 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
1f350 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1f360 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
1f370 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
1f380 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
1f390 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1f3a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f3b0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1f3c0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
1f3d0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
1f3e0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1f3f0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
1f400 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1f410 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1f420 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1f430 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1f440 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1f450 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1f460 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1f470 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1f480 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1f490 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1f4a0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1f4b0 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
1f4c0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
1f4d0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1f4e0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1f4f0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1f500 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1f510 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1f520 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1f530 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1f540 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
1f550 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1f560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1f570 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1f580 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1f590 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1f5a0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1f5b0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
1f5c0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
1f5d0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1f5e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1f5f0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
1f600 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
1f610 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1f620 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1f630 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1f640 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1f650 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1f660 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1f670 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1f680 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1f690 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
1f6a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
1f6b0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
1f6c0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
1f6d0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
1f6e0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
1f6f0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
1f700 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
1f710 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
1f720 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
1f730 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
1f740 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
1f750 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
1f760 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
1f770 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
1f780 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
1f790 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
1f7a0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
1f7b0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
1f7c0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
1f7d0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
1f7e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f7f0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1f800 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
1f810 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
1f820 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
1f830 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
1f840 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
1f850 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
1f860 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
1f870 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
1f880 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
1f890 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
1f8a0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
1f8b0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
1f8c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f8d0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
1f8e0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
1f8f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
1f900 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32  ITE_ENABLE_STAT2
1f910 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f920 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
1f930 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
1f940 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1f950 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1f960 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1f970 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1f980 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1f990 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f9a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1f9b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1f9c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1f9d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f9e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f9f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1fa00 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1fa10 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1fa20 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1fa30 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1fa40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1fa50 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1fa60 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1fa70 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1fa80 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1fa90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1faa0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1fab0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1fac0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1fad0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1fae0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1faf0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1fb00 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1fb10 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1fb20 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1fb30 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1fb40 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1fb50 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1fb60 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1fb70 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1fb80 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1fb90 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1fba0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1fbb0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1fbc0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1fbd0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1fbe0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1fbf0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1fc00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1fc10 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1fc20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1fc30 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1fc40 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1fc50 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1fc60 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1fc70 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1fc80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1fc90 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1fca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1fcb0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1fcc0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1fcd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1fce0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1fcf0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1fd00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1fd10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1fd20 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1fd30 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1fd40 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1fd50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1fd60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1fd70 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1fd80 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1fd90 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1fda0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1fdb0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1fdc0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1fdd0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1fde0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1fdf0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1fe00 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1fe10 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1fe20 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1fe30 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1fe40 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1fe50 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1fe60 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1fe70 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1fe80 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1fe90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1fea0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1feb0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1fec0 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1fed0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1fee0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1fef0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1ff00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1ff10 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1ff20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1ff30 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1ff40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ff50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ff60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1ff70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ff80 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1ff90 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1ffa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ffb0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1ffc0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1ffd0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
1ffe0 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
1fff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
20000 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
20010 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
20020 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
20030 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
20040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20050 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
20060 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
20070 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
20080 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
20090 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
200a0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
200b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
200c0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
200d0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
200e0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
200f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
20100 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
20110 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
20120 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
20130 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
20140 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
20150 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
20160 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
20170 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
20180 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
20190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
201a0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
201b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
201c0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
201d0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
201e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
201f0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
20200 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
20210 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
20220 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
20230 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
20240 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
20250 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
20260 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
20270 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
20280 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
20290 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
202a0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
202b0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
202c0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
202d0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
202e0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
202f0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
20300 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
20310 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
20320 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
20330 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
20340 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
20350 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
20360 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
20370 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
20380 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
20390 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
203a0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
203b0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
203c0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
203d0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
203e0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
203f0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
20400 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
20410 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
20420 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
20430 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
20440 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
20450 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
20460 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
20470 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
20480 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
20490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
204a0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
204b0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
204c0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
204d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
204e0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
204f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
20500 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
20510 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
20520 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20530 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
20540 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
20550 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
20560 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
20570 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
20580 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20590 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
205a0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
205b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
205c0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
205d0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
205e0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
205f0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
20600 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
20610 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
20620 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
20630 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
20640 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
20650 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20660 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
20670 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
20680 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
20690 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
206a0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
206b0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
206c0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
206d0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
206e0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
206f0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
20700 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
20710 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20720 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
20730 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
20740 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
20750 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
20760 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
20770 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
20780 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
20790 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
207a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
207b0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
207c0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
207d0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
207e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
207f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
20800 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
20810 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
20820 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
20830 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
20840 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
20850 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
20860 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
20870 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
20880 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20890 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
208a0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
208b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
208c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
208d0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
208e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
208f0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
20900 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
20910 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
20920 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
20930 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
20940 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
20950 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
20960 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
20970 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
20980 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
20990 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
209a0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
209b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
209c0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
209d0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
209e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
209f0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
20a00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20a10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20a20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
20a30 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
20a40 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
20a50 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
20a60 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
20a70 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
20a80 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
20a90 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
20aa0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
20ab0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
20ac0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
20ad0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
20ae0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
20af0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
20b00 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
20b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20b20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
20b30 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
20b40 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
20b50 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
20b60 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
20b70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20b80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
20b90 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
20ba0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
20bb0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
20bc0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
20bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
20be0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
20bf0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
20c00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
20c10 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
20c20 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
20c30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
20c40 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
20c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20c60 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
20c70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
20c80 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
20c90 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
20ca0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
20cb0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
20cc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20cd0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
20ce0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
20cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
20d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20d10 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
20d20 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
20d30 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
20d40 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
20d50 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
20d60 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
20d70 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
20d80 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
20d90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
20da0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
20db0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
20dc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
20dd0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
20de0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
20df0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
20e00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
20e10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
20e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
20e30 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
20e40 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
20e50 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
20e60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
20e70 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
20e80 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
20e90 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
20ea0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
20eb0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
20ec0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
20ed0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
20ee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
20ef0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
20f00 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
20f10 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
20f20 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
20f30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
20f40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
20f50 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
20f60 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
20f70 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
20f80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
20f90 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
20fa0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
20fb0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
20fc0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
20fd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
20fe0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
20ff0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
21000 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
21010 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
21020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21030 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
21040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21050 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
21060 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
21070 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
21080 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
21090 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
210a0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
210b0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
210c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
210d0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
210e0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
210f0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
21100 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
21110 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
21120 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
21130 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
21140 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
21150 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
21160 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
21170 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
21180 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
21190 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
211a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
211b0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
211c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
211d0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
211e0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
211f0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
21200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
21210 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
21220 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
21230 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21240 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
21250 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
21260 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
21270 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
21280 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
21290 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
212a0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
212b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
212c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
212d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
212e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
212f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
21300 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
21310 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
21320 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
21330 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
21340 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
21350 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
21360 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
21370 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
21380 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
21390 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
213a0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
213b0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
213c0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
213d0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
213e0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
213f0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
21400 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
21410 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
21420 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21430 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
21440 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
21450 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
21460 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
21470 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
21480 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
21490 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
214a0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
214b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
214c0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
214d0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
214e0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
214f0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
21500 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
21510 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
21520 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
21530 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
21540 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
21550 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
21560 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
21570 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
21580 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
21590 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
215a0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
215b0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
215c0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
215d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
215e0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
215f0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
21600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
21610 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
21620 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
21630 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
21640 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
21650 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
21660 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
21670 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
21680 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
21690 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
216a0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
216b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
216c0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
216d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
216e0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
216f0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
21700 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
21710 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
21720 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
21730 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
21740 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
21750 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
21760 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
21770 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
21780 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
21790 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
217a0 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
217b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
217c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
217d0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
217e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
217f0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
21800 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
21810 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
21820 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
21830 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
21840 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
21850 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
21860 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
21870 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
21880 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
21890 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
218a0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
218b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
218c0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
218d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
218e0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
218f0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
21900 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
21910 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
21920 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
21930 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
21940 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
21950 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
21960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
21970 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
21980 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
21990 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
219a0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
219b0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
219c0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
219d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
219e0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
219f0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
21a00 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
21a10 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
21a20 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
21a30 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
21a40 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
21a50 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
21a60 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
21a70 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
21a80 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
21a90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
21aa0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
21ab0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
21ac0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
21ad0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
21ae0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
21af0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
21b00 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
21b10 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
21b20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21b30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
21b40 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
21b50 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
21b60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21b70 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
21b80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
21b90 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
21ba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21bb0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
21bc0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
21bd0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
21be0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
21bf0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
21c00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
21c10 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
21c20 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
21c30 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
21c40 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
21c50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
21c60 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
21c70 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
21c80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
21c90 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
21ca0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
21cb0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
21cc0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
21cd0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
21ce0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
21cf0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
21d00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21d10 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
21d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
21d30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21d40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
21d50 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
21d60 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
21d70 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
21d80 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
21d90 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
21da0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
21db0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
21dc0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
21dd0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
21de0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
21df0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
21e00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
21e10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21e20 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
21e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21e40 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21e50 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
21e60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21e70 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
21e80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
21e90 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21ea0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
21eb0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
21ec0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
21ed0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
21ee0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
21ef0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
21f00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
21f10 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
21f20 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
21f30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21f40 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
21f50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
21f60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
21f70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
21f80 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
21f90 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
21fa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
21fb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21fc0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
21fd0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21fe0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
21ff0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
22000 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22010 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
22020 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
22030 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
22040 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
22050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22060 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
22070 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
22080 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
22090 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
220a0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
220b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
220c0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
220d0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
220e0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
220f0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
22100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
22110 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
22120 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
22130 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
22140 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
22150 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
22160 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
22170 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
22180 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
22190 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
221a0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
221b0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
221c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
221d0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
221e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
221f0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
22200 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
22210 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
22220 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
22230 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
22240 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
22250 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
22260 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
22270 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
22280 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
22290 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
222a0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
222b0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
222c0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
222d0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
222e0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
222f0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
22300 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22320 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22330 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
22340 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
22350 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
22360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22370 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
22380 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
22390 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
223a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
223b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
223c0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
223d0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
223e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
223f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22400 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
22410 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
22420 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
22430 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
22440 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
22450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22460 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
22470 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
22480 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
22490 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
224a0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
224b0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
224c0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
224d0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
224e0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
224f0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
22500 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
22510 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
22520 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
22530 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
22540 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
22550 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
22560 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
22570 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
22580 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
22590 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
225a0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
225b0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
225c0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
225d0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
225e0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
225f0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
22600 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
22610 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
22620 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
22630 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
22640 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
22650 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
22660 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
22670 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
22680 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
22690 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
226a0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
226b0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
226c0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
226d0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
226e0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
226f0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
22700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22710 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
22720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22730 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
22740 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
22750 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
22760 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
22770 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22780 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
22790 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
227a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
227b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
227c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
227d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
227e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
227f0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
22800 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
22810 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
22820 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
22830 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
22840 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
22850 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
22860 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
22870 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
22880 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
22890 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
228a0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
228b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
228c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
228d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
228e0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
228f0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
22900 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
22910 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
22920 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
22930 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
22940 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
22950 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
22960 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
22970 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
22980 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
22990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
229a0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
229b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
229c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
229d0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
229e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
229f0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22a00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
22a10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22a20 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
22a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22a40 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
22a50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22a60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
22a70 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
22a80 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
22a90 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
22aa0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
22ab0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
22ac0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
22ad0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
22ae0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
22af0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
22b00 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
22b10 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
22b20 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
22b30 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
22b40 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
22b50 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
22b60 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
22b70 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
22b80 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
22b90 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
22ba0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
22bb0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
22bc0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
22bd0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
22be0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
22bf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
22c00 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
22c10 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
22c20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22c30 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
22c40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
22c50 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
22c60 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
22c70 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
22c80 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
22c90 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
22ca0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
22cb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
22cc0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
22cd0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
22ce0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
22cf0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22d00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
22d10 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
22d20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
22d30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
22d40 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
22d50 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
22d60 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
22d70 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
22d80 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
22d90 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
22da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
22db0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
22dc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22dd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
22de0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
22df0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
22e00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
22e10 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
22e20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
22e30 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
22e40 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
22e50 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
22e60 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
22e70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22e80 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
22e90 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
22ea0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
22eb0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
22ec0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
22ed0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
22ee0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
22ef0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
22f00 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
22f10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
22f20 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
22f30 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
22f40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22f50 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
22f60 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
22f70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22f80 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
22f90 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
22fa0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
22fb0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
22fc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22fd0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
22fe0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
22ff0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
23000 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
23010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23020 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
23030 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
23040 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
23050 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
23060 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
23070 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
23080 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
23090 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
230a0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
230b0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
230c0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
230d0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
230e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
230f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23100 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
23110 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
23120 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
23130 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
23140 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
23150 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
23160 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
23170 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
23180 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
23190 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
231a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
231b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
231c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
231d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
231e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
231f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23210 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23220 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
23230 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23240 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
23250 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
23260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23270 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
23280 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
23290 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
232a0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
232b0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
232c0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
232d0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
232e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
232f0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
23300 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
23310 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
23320 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
23330 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
23340 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
23350 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
23360 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
23370 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
23380 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
23390 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
233a0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
233b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
233c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
233d0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
233e0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
233f0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
23400 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
23410 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
23420 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
23430 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
23440 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
23450 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
23460 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23470 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
23480 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
23490 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
234a0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
234b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
234c0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
234d0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
234e0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
234f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
23500 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
23510 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
23520 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
23530 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
23540 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
23550 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
23560 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
23570 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
23580 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
23590 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
235a0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
235b0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
235c0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
235d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
235e0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
235f0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
23600 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
23610 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
23620 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
23630 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
23640 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
23650 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
23660 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
23670 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
23680 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
23690 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
236a0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
236b0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
236c0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
236d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
236e0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
236f0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
23700 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
23710 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
23720 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
23730 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
23740 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
23750 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
23760 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
23770 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
23780 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
23790 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
237a0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
237b0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
237c0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
237d0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
237e0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
237f0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
23800 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
23810 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
23820 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
23830 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
23840 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
23850 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
23860 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
23870 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
23880 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
23890 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
238a0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
238b0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
238c0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
238d0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
238e0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
238f0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
23900 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
23910 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
23920 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
23930 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
23940 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
23950 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
23960 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
23970 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
23980 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
23990 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
239a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
239b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
239c0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
239d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
239e0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
239f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
23a00 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
23a10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
23a20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23a30 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
23a40 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
23a50 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
23a60 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
23a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23a80 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
23a90 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
23aa0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
23ab0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
23ac0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
23ad0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
23ae0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
23af0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
23b00 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
23b10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23b20 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
23b30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23b40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
23b50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23b60 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
23b70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23b80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
23ba0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
23bb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
23bc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23bd0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
23be0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
23bf0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
23c00 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23c10 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
23c20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23c30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23c40 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
23c50 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
23c60 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
23c70 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
23c80 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
23c90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23ca0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
23cb0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
23cc0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
23cd0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23ce0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
23cf0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
23d00 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
23d10 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
23d20 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
23d30 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
23d40 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
23d50 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
23d60 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
23d70 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
23d80 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
23d90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
23da0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
23db0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
23dc0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
23dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
23de0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
23df0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
23e00 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
23e10 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
23e20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
23e30 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
23e40 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
23e50 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
23e60 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
23e70 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
23e80 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
23e90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
23ea0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
23eb0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
23ec0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
23ed0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
23ee0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
23ef0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
23f00 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
23f10 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
23f20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23f30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
23f40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
23f50 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
23f60 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
23f70 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
23f80 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
23f90 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
23fa0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
23fb0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
23fc0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
23fd0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
23fe0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
23ff0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
24000 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
24010 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
24020 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
24030 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
24040 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
24050 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
24060 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
24070 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
24080 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
24090 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
240a0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
240b0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
240c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
240d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
240e0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
240f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
24100 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24110 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
24120 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
24130 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
24140 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
24150 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
24160 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
24170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24180 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
24190 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
241a0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
241b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
241c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
241d0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
241e0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
241f0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
24200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
24210 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24220 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
24230 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
24240 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
24250 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
24260 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
24270 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
24280 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
24290 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
242a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
242b0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
242c0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
242d0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
242e0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
242f0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
24300 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
24310 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24320 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24330 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
24340 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
24350 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
24360 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24370 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24380 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
24390 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
243a0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
243b0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
243c0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
243d0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
243e0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
243f0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
24400 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
24410 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
24420 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
24430 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
24440 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
24450 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
24460 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
24470 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
24480 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
24490 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
244a0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
244b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
244c0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
244d0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
244e0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
244f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24500 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
24510 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
24520 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
24530 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
24540 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
24550 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
24560 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
24570 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
24580 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
24590 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
245a0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
245b0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
245c0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
245d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
245e0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
245f0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
24600 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
24610 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
24620 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
24630 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
24640 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
24650 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
24660 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
24670 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
24680 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
24690 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
246a0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
246b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
246c0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
246d0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
246e0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
246f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
24700 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
24710 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
24720 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
24730 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
24740 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
24750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
24760 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
24770 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
24780 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
24790 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
247a0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
247b0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
247c0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
247d0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
247e0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
247f0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
24800 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
24810 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
24820 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
24830 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
24840 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
24850 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
24860 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
24870 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
24880 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
24890 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
248a0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
248b0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
248c0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
248d0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
248e0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
248f0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
24900 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
24910 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
24920 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
24930 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
24940 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
24950 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
24960 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
24970 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
24980 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
24990 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
249a0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
249b0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
249c0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
249d0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
249e0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
249f0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
24a00 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
24a10 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
24a20 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
24a30 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
24a40 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
24a50 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
24a60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24a70 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
24a80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
24a90 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
24aa0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
24ab0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
24ac0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
24ad0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
24ae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
24af0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
24b00 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
24b10 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
24b20 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
24b30 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
24b40 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
24b50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
24b60 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
24b70 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
24b80 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
24b90 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
24ba0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
24bb0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
24bc0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
24bd0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
24be0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
24bf0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
24c00 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
24c10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24c20 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
24c30 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
24c40 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
24c50 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
24c60 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
24c70 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24c80 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
24c90 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
24ca0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
24cb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24cc0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
24cd0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
24ce0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
24cf0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
24d00 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
24d10 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
24d20 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
24d30 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
24d40 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
24d50 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
24d60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
24d70 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
24d80 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
24d90 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
24da0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
24db0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
24dc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
24dd0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
24de0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
24df0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
24e00 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
24e10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
24e20 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
24e30 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
24e40 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
24e50 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
24e60 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
24e70 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
24e80 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
24e90 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
24ea0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
24eb0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
24ec0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
24ed0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
24ee0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
24ef0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
24f00 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
24f10 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
24f20 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
24f30 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
24f40 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
24f50 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
24f60 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
24f70 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
24f80 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
24f90 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
24fa0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
24fb0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
24fc0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
24fd0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
24fe0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
24ff0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
25000 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
25010 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
25020 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
25030 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
25040 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
25050 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25060 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
25070 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
25080 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
25090 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
250a0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
250b0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
250c0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
250d0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
250e0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
250f0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
25100 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
25110 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
25120 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
25130 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
25140 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
25150 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
25160 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
25180 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
25190 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
251a0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
251b0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
251c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
251d0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
251e0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
251f0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
25200 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
25210 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
25220 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
25230 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
25240 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
25250 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
25260 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25270 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
25280 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
25290 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
252a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
252b0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
252c0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
252d0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
252e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
252f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
25300 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
25310 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
25320 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
25330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25340 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
25350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
25360 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
25370 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
25380 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
25390 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
253a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
253b0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
253c0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
253d0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
253e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
253f0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
25400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
25410 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
25420 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
25430 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
25440 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
25450 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
25470 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
25480 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
25490 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
254a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
254b0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
254c0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
254d0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
254e0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
254f0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
25500 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
25510 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
25520 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
25530 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
25540 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
25550 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
25560 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
25570 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
25580 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
25590 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
255a0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
255b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
255c0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
255d0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
255e0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
255f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
25600 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
25610 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
25620 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
25630 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
25640 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
25650 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
25660 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
25670 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
25680 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
25690 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
256a0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
256b0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
256c0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
256d0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
256e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
256f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
25700 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
25710 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
25720 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
25730 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
25740 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
25750 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
25760 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
25770 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
25780 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
25790 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
257a0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
257b0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
257c0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
257d0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
257e0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
257f0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
25800 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25810 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
25820 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
25830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
25840 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
25850 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
25860 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
25870 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
25880 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
25890 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
258a0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
258b0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
258c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
258d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
258e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
258f0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
25900 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
25910 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
25920 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
25930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25940 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
25950 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
25960 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
25970 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
25980 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
25990 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
259a0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
259b0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
259c0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
259d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
259e0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
259f0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
25a00 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25a10 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
25a20 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
25a30 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
25a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
25a50 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
25a60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
25a70 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
25a80 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
25a90 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
25aa0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
25ab0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
25ac0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
25ad0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25ae0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25af0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
25b00 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
25b10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
25b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
25b30 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
25b40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
25b50 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
25b60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
25b70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
25b80 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
25b90 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
25ba0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
25bb0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25bc0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
25bd0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
25be0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
25bf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25c00 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
25c10 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
25c20 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
25c30 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
25c40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
25c50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
25c60 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
25c70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25c80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
25c90 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
25ca0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
25cb0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
25cc0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
25cd0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
25ce0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
25cf0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
25d00 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
25d10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
25d20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25d30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
25d40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
25d50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
25d60 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
25d70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
25d80 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
25d90 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
25da0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
25db0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
25dc0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
25dd0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
25de0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
25df0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
25e00 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
25e10 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
25e20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
25e30 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
25e40 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
25e50 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
25e60 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
25e70 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
25e80 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
25e90 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
25ea0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
25eb0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
25ec0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
25ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ee0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
25ef0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
25f00 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
25f10 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
25f20 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
25f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
25f40 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
25f50 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
25f60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
25f70 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
25f80 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
25f90 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
25fa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25fb0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
25fc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
25fd0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
25fe0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
25ff0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
26000 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
26010 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
26020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26030 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
26040 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
26050 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
26060 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
26070 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
26080 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
26090 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
260a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
260b0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
260c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
260d0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
260e0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
260f0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
26100 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
26110 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
26120 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
26130 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
26140 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
26150 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
26160 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
26170 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
26180 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
26190 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
261a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
261b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
261c0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
261d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
261e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
261f0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
26200 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
26210 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
26220 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
26230 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
26240 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
26250 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
26260 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
26270 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
26280 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
26290 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
262a0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
262b0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
262c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
262d0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
262e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
262f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
26300 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
26310 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
26320 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
26330 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26340 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
26350 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
26360 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
26370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26380 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
26390 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
263a0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
263b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
263c0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
263d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
263e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
263f0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
26400 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
26410 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
26420 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
26430 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
26440 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
26450 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
26460 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
26470 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26480 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
26490 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
264a0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
264b0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
264c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
264d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
264e0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
264f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26500 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
26510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26520 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
26530 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
26540 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
26550 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
26560 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
26570 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
26580 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
26590 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
265a0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
265b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
265c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
265d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
265e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
265f0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
26600 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26610 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
26620 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26630 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
26640 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
26650 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
26660 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
26670 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
26680 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
26690 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
266a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
266b0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
266c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
266d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
266e0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
266f0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
26700 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
26710 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
26720 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
26730 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
26740 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
26750 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
26760 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
26770 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26780 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
26790 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
267a0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
267b0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
267c0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
267d0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
267e0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
267f0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
26800 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
26810 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
26820 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
26830 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
26840 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
26850 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
26860 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
26870 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
26880 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
26890 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
268a0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
268b0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
268c0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
268d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
268e0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
268f0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
26900 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
26910 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
26920 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
26930 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
26940 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
26950 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
26960 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
26970 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
26980 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
26990 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
269a0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
269b0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
269c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
269d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
269e0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
269f0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
26a00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
26a10 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
26a20 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
26a30 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
26a40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
26a50 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
26a60 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
26a70 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
26a80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
26a90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
26aa0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
26ab0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
26ac0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
26ad0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
26ae0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
26af0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
26b00 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
26b10 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
26b20 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
26b30 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
26b40 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
26b50 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
26b60 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
26b70 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
26b80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
26b90 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
26ba0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
26bb0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
26bc0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
26bd0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
26be0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
26bf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
26c00 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
26c10 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
26c20 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
26c30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
26c40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
26c50 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
26c60 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
26c70 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
26c80 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
26c90 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
26ca0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
26cb0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
26cc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
26cd0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
26ce0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
26cf0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
26d00 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
26d10 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
26d20 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
26d30 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
26d40 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
26d50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
26d60 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
26d70 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
26d80 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
26d90 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
26da0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
26db0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
26dc0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
26dd0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
26de0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
26df0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
26e00 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
26e10 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
26e20 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
26e30 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
26e40 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
26e50 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
26e60 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
26e70 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
26e80 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
26e90 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
26ea0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
26eb0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
26ec0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
26ed0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
26ee0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
26ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26f00 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
26f10 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
26f20 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
26f30 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
26f40 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
26f50 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
26f60 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
26f70 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
26f80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
26f90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
26fa0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
26fb0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
26fc0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
26fd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
26fe0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
26ff0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
27000 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
27010 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
27020 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
27030 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
27040 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
27050 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
27060 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
27070 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
27080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27090 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
270a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
270b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
270c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
270d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
270e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
270f0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
27100 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
27110 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
27120 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
27130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27140 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
27150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27160 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
27170 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
27180 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
27190 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
271a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
271b0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
271c0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
271d0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
271e0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
271f0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
27200 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
27210 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
27220 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
27230 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
27240 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
27250 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
27260 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
27270 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
27280 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
27290 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
272a0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
272b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
272c0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
272d0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
272e0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
272f0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
27300 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
27310 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
27320 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
27330 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
27340 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
27350 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
27360 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
27370 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
27380 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
27390 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
273a0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
273b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
273c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
273d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
273e0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
273f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
27400 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
27410 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27420 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
27430 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
27440 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
27450 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
27460 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27470 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
27480 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
27490 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
274a0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
274b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
274c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
274d0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
274e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
274f0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
27500 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
27510 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
27520 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
27530 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
27540 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
27550 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
27560 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
27570 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
27580 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
27590 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
275a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
275b0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
275c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
275d0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
275e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
275f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
27600 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
27610 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
27620 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
27630 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
27640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27650 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
27660 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
27670 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
27680 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
27690 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
276a0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
276b0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
276c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
276d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
276e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
276f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
27700 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
27710 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
27720 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
27730 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
27740 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
27750 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
27760 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
27770 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
27780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
27790 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
277a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
277b0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
277c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
277d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
277e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
277f0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
27800 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
27810 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
27820 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27830 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
27840 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
27850 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
27860 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
27870 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
27880 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
27890 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
278a0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
278b0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
278c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
278d0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
278e0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
278f0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
27900 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27920 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27930 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
27940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27950 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
27960 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
27970 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
27980 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
27990 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
279a0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
279b0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
279c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
279d0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
279e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
279f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27a00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
27a10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
27a20 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
27a30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27a40 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
27a50 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
27a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27a70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27a80 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
27a90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27aa0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
27ab0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27ac0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
27ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
27ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27af0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
27b00 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
27b10 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
27b20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27b30 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
27b40 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
27b50 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
27b60 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
27b70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
27b80 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
27b90 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
27ba0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
27bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
27bc0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
27bd0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
27be0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
27bf0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
27c00 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72   errors or.** or
27c10 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
27c20 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
27c30 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
27c40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27c50 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
27c60 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
27c70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
27c80 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
27c90 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
27ca0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
27cb0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
27cc0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
27cd0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
27ce0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
27cf0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
27d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27d10 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
27d20 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
27d30 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
27d40 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
27d50 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
27d60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27d70 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
27d80 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
27d90 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
27da0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
27db0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
27dc0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
27dd0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
27de0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
27df0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
27e00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27e10 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
27e20 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
27e30 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
27e40 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
27e50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27e60 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
27e70 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
27e80 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
27e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
27ea0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
27eb0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
27ec0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
27ed0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
27ee0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
27ef0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
27f00 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
27f10 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
27f20 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
27f30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
27f40 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
27f50 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
27f60 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
27f70 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
27f80 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
27f90 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
27fa0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
27fb0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
27fc0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
27fd0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
27fe0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
27ff0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
28000 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
28010 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28020 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28030 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
28040 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28050 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
28060 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
28070 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
28080 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
28090 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
280a0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
280b0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
280c0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
280d0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
280e0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
280f0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
28100 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
28110 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
28120 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
28130 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
28140 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
28150 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
28160 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
28170 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
28180 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
28190 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
281a0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
281b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
281c0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
281d0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
281e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
281f0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
28200 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
28210 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
28220 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
28230 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
28240 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
28250 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
28270 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
28280 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
28290 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
282a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
282b0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
282c0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
282d0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
282e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
282f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
28300 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
28310 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
28320 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28330 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
28340 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28350 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
28360 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
28370 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
28380 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
28390 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
283a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
283b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
283c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
283d0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
283e0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
283f0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
28400 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
28410 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
28420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28430 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
28440 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
28450 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28470 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
28480 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
28490 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
284a0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
284b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
284c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
284d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
284e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
284f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
28500 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28510 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
28520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
28530 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
28540 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
28550 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
28560 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
28570 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
28580 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
28590 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
285a0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
285b0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
285c0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
285d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
285e0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
285f0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
28600 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
28610 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
28620 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
28630 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
28640 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
28650 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
28660 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
28670 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
28680 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
28690 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
286a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
286b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
286c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
286d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
286e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
286f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
28700 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
28710 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
28720 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
28730 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
28740 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
28750 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
28760 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28770 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
28780 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
287a0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
287b0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
287c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
287d0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
287e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
287f0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
28800 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
28810 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
28820 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
28830 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
28840 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
28850 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
28860 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
28870 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
28880 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
28890 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
288a0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
288b0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
288c0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
288d0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
288e0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
288f0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
28900 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
28910 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
28920 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
28930 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
28940 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
28950 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
28960 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
28970 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28980 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
28990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
289a0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
289b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
289c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
289d0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
289e0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
289f0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
28a00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
28a10 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
28a20 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
28a30 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
28a40 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
28a50 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
28a60 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
28a70 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28a80 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
28a90 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
28aa0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
28ab0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
28ac0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
28ad0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
28ae0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
28af0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28b00 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
28b10 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
28b20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
28b30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
28b40 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
28b50 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
28b60 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
28b70 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
28b80 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28b90 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
28ba0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
28bb0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
28bc0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
28bd0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
28be0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
28bf0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
28c00 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
28c10 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
28c20 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
28c30 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
28c40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28c50 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
28c60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28c70 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
28c80 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
28c90 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
28ca0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
28cb0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
28cc0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
28cd0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
28ce0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
28cf0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
28d00 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
28d10 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
28d20 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
28d30 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
28d40 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
28d50 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
28d60 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
28d70 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
28d80 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
28d90 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
28da0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
28db0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
28dc0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
28dd0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
28de0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
28df0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
28e00 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
28e10 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
28e20 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
28e30 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
28e40 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
28e50 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
28e60 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
28e70 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
28e80 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
28e90 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
28ea0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
28eb0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
28ec0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
28ed0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
28ee0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
28ef0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
28f00 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
28f10 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
28f20 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
28f30 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
28f40 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
28f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28f60 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
28f70 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
28f80 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
28f90 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
28fa0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
28fb0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
28fc0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
28fd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28fe0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28ff0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
29000 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
29010 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
29020 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
29030 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
29040 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
29050 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
29060 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
29070 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
29080 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
29090 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
290a0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
290b0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
290c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
290d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
290e0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
290f0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
29100 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
29110 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29120 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
29130 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
29140 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
29150 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
29160 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
29170 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
29180 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
29190 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
291a0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
291b0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
291c0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
291d0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
291e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
291f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
29200 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
29210 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
29220 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
29230 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
29240 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
29250 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
29260 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
29270 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
29280 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29290 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
292a0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
292b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
292c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
292d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
292e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
292f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
29300 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
29310 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
29320 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
29330 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
29340 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
29350 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
29360 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
29370 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
29380 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
29390 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
293a0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
293b0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
293c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
293d0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
293e0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
293f0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
29400 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
29410 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
29420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29430 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
29440 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
29450 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
29460 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
29470 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
29480 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
29490 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
294a0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
294b0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
294c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
294d0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
294e0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
294f0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
29500 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
29510 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
29520 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
29530 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
29540 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
29550 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
29560 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
29570 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
29580 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
29590 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
295a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
295b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
295c0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
295d0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
295e0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
295f0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
29600 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
29610 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
29620 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29630 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
29640 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29650 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
29660 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
29670 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
29680 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
29690 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
296a0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
296b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
296c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
296d0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
296e0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
296f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
29700 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
29710 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
29720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
29730 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
29740 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
29750 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
29760 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
29770 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
29780 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
29790 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
297a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
297b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
297c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
297d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
297e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
297f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
29800 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
29810 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
29820 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
29830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29840 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
29850 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
29860 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
29870 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
29880 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
29890 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
298a0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
298b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
298c0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
298d0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
298e0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
298f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
29900 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
29910 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
29920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
29930 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
29950 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
29960 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
29970 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
29980 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
29990 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
299a0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
299b0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
299c0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
299d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
299e0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
299f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29a00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
29a10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
29a20 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
29a30 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
29a40 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
29a50 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
29a60 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
29a70 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
29a80 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
29a90 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
29aa0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
29ab0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
29ac0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
29ad0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
29ae0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
29af0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
29b00 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
29b10 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
29b20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
29b30 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
29b40 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
29b50 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
29b60 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
29b70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
29b80 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
29b90 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
29ba0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
29bb0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29bc0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
29bd0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
29be0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
29bf0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29c00 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
29c10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
29c20 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
29c30 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
29c40 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
29c50 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
29c60 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
29c70 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
29c80 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
29c90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
29ca0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
29cb0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
29cc0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
29cd0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
29ce0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
29cf0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
29d00 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
29d10 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
29d20 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
29d30 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
29d40 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
29d50 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29d60 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
29d70 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
29d80 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
29d90 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
29da0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
29db0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
29dc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
29dd0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
29de0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
29df0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
29e00 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
29e10 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
29e20 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
29e30 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
29e40 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
29e50 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
29e60 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
29e70 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
29e80 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
29e90 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
29ea0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
29eb0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
29ec0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
29ed0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
29ee0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
29f00 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
29f10 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
29f20 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
29f30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
29f40 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29f50 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
29f60 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
29f70 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
29f80 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
29f90 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
29fa0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
29fb0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
29fc0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
29fd0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
29fe0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
29ff0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2a000 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2a010 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2a020 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2a030 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2a040 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2a050 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2a060 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2a070 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2a080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a090 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2a0a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a0b0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2a0c0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2a0d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2a0e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2a0f0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2a100 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2a110 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2a120 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2a130 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2a140 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2a150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a160 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2a170 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2a180 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2a190 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2a1a0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2a1b0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2a1c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2a1d0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2a1e0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2a1f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a200 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2a210 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2a220 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2a230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a240 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2a250 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2a260 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2a270 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2a280 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a290 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2a2a0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2a2b0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2a2c0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2a2d0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2a2e0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2a2f0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2a300 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2a310 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2a320 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a330 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2a340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a350 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2a360 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2a370 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2a380 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2a390 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2a3a0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2a3b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a3c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2a3d0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2a3e0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2a3f0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2a400 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2a410 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2a420 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2a430 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a440 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2a450 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2a460 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2a470 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2a480 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2a490 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2a4a0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2a4b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
2a4c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2a4d0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2a4e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2a4f0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2a500 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2a510 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2a520 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2a530 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2a540 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2a550 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2a560 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2a570 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2a580 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2a590 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2a5a0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2a5b0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2a5c0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2a5d0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2a5e0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2a5f0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2a600 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2a610 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2a620 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2a630 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2a640 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2a650 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2a660 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2a670 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2a680 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
2a690 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2a6a0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2a6b0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2a6c0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2a6d0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2a6e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2a6f0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2a700 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2a710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2a720 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2a730 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2a740 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2a750 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2a760 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2a770 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2a780 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2a790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a7a0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2a7b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a7c0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2a7d0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2a7e0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2a7f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2a800 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2a810 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2a820 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2a830 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2a840 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
2a850 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2a860 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2a870 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2a880 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a890 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a8a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2a8b0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2a8c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2a8d0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2a8e0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2a8f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2a900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2a910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a920 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2a930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2a940 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2a950 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2a960 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2a970 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2a980 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2a990 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a9a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2a9b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2a9c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a9d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2a9e0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2a9f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2aa00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2aa10 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2aa20 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2aa30 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2aa40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2aa50 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2aa60 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2aa70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2aa80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2aa90 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2aaa0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2aab0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
2aac0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
2aad0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2aae0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
2aaf0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2ab00 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
2ab10 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2ab20 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2ab30 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2ab40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ab50 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2ab60 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
2ab70 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
2ab80 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
2ab90 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
2aba0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
2abb0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
2abc0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
2abd0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2abe0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2abf0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
2ac00 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2ac10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
2ac20 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2ac30 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
2ac40 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
2ac50 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2ac60 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
2ac70 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2ac80 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
2ac90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2aca0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
2acb0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
2acc0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
2acd0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
2ace0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
2acf0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
2ad00 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
2ad10 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
2ad20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
2ad30 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
2ad40 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
2ad50 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
2ad60 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
2ad70 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2ad80 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
2ad90 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
2ada0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
2adb0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
2adc0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
2add0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
2ade0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2adf0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
2ae00 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
2ae10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
2ae20 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
2ae30 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
2ae40 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
2ae50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2ae60 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
2ae70 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
2ae80 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
2ae90 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
2aea0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
2aeb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
2aec0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
2aed0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
2aee0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
2aef0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
2af00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2af10 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
2af20 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
2af30 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
2af40 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
2af50 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
2af60 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
2af70 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
2af80 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
2af90 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2afa0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
2afb0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2afc0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2afd0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
2afe0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2aff0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
2b000 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
2b010 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2b020 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2b030 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
2b040 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2b050 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
2b060 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
2b070 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2b080 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2b090 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
2b0a0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
2b0b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2b0c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2b0d0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2b0e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b0f0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
2b100 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
2b110 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2b120 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2b130 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
2b140 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2b150 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2b160 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2b170 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2b180 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2b190 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2b1a0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2b1b0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2b1c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2b1d0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2b1e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2b1f0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2b200 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2b210 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
2b220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b230 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2b240 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b250 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2b260 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2b270 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2b280 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2b290 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2b2a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b2b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b2c0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2b2d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b2e0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2b2f0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2b300 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2b310 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2b320 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2b330 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b340 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2b350 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2b360 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2b370 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2b380 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b390 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2b3a0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2b3b0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2b3c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2b3d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b3e0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2b3f0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2b400 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2b410 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2b420 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2b430 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2b440 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2b450 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2b460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b470 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2b480 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2b490 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b4a0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2b4b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2b4c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2b4d0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2b4e0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2b4f0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2b500 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2b510 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
2b520 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2b530 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2b540 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b560 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2b570 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
2b580 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2b590 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2b5a0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2b5b0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2b5c0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2b5d0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2b5e0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2b5f0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2b600 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2b610 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2b620 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2b630 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2b640 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2b650 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2b660 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2b670 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2b680 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2b690 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2b6a0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2b6b0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2b6c0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2b6d0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2b6e0 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2b6f0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2b700 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2b710 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2b720 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2b730 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2b740 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2b750 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2b760 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2b770 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2b780 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2b790 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2b7a0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2b7b0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2b7c0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2b7d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2b7e0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2b7f0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2b800 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2b810 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2b820 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2b830 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2b840 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
2b850 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2b860 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2b870 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b880 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
2b890 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
2b8a0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
2b8b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
2b8c0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
2b8d0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
2b8e0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
2b8f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b900 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
2b910 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
2b920 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
2b930 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
2b940 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2b950 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
2b960 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2b970 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
2b980 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
2b990 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
2b9a0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
2b9b0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
2b9c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
2b9d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2b9e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2b9f0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2ba00 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2ba10 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2ba20 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
2ba30 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
2ba40 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
2ba50 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
2ba60 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2ba70 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2ba80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2ba90 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2baa0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2bab0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2bac0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2bad0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2bae0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2baf0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2bb00 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
2bb10 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2bb20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2bb30 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2bb40 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2bb50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2bb60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2bb70 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2bb80 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2bb90 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2bba0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2bbb0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2bbc0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2bbd0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2bbe0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2bbf0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2bc00 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2bc10 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2bc20 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2bc30 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2bc40 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2bc50 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2bc60 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
2bc70 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
2bc80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
2bc90 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
2bca0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
2bcb0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
2bcc0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
2bcd0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2bce0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2bcf0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2bd00 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2bd10 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2bd20 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2bd30 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2bd40 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2bd50 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2bd60 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
2bd70 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
2bd80 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2bd90 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2bda0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2bdb0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
2bdc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2bdd0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2bde0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2bdf0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2be00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
2be10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2be20 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2be30 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
2be40 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
2be50 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
2be60 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
2be70 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
2be80 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
2be90 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
2bea0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2beb0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
2bec0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2bed0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2bee0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2bef0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2bf00 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2bf10 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2bf20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
2bf30 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2bf40 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2bf50 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2bf60 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2bf70 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2bf80 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2bf90 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2bfa0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2bfb0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
2bfc0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
2bfd0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2bfe0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2bff0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2c000 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2c010 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2c020 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2c030 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2c040 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2c050 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2c060 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2c070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2c080 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2c090 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2c0a0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2c0b0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2c0c0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2c0d0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2c0e0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2c0f0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2c100 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2c110 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2c120 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2c130 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2c140 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2c150 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2c160 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2c170 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2c180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2c190 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2c1a0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2c1b0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
2c1c0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2c1d0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
2c1e0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2c1f0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
2c200 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
2c210 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2c220 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
2c230 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c240 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2c250 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c260 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
2c270 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2c280 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2c290 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
2c2a0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
2c2b0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
2c2c0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
2c2d0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
2c2e0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
2c2f0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
2c300 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
2c310 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
2c320 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
2c330 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
2c340 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2c350 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2c360 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
2c370 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c380 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2c390 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2c3a0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2c3b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c3c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c3d0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2c3e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2c3f0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2c400 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2c410 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2c420 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2c430 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2c440 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
2c450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c460 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2c470 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
2c480 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
2c490 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2c4a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c4b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
2c4c0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
2c4d0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
2c4e0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
2c4f0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
2c500 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2c510 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
2c520 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c530 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2c540 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2c550 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2c560 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2c570 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c580 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
2c590 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c5a0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
2c5b0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
2c5c0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2c5d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c5e0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2c5f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c600 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
2c610 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
2c620 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
2c630 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
2c640 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
2c650 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2c660 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2c670 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2c680 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2c690 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2c6a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2c6b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2c6c0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2c6d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2c6e0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
2c6f0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2c700 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2c710 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2c720 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2c730 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
2c740 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
2c750 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2c760 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c770 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
2c780 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
2c790 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
2c7a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c7b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2c7c0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2c7d0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2c7e0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2c7f0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2c800 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2c810 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2c820 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2c830 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2c840 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2c850 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2c860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c870 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c880 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2c890 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2c8a0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2c8b0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2c8c0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2c8d0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2c8e0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2c8f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2c900 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2c910 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
2c920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c930 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2c940 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c950 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
2c960 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
2c970 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
2c980 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
2c990 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
2c9a0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
2c9b0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
2c9c0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
2c9d0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
2c9e0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
2c9f0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
2ca00 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
2ca10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ca20 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
2ca30 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
2ca40 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
2ca50 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
2ca60 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
2ca70 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
2ca80 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
2ca90 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
2caa0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
2cab0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
2cac0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2cad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2cae0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2caf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2cb00 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2cb10 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2cb20 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2cb30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2cb40 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
2cb50 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2cb60 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2cb70 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2cb80 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
2cb90 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
2cba0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
2cbb0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
2cbc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cbd0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
2cbe0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
2cbf0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2cc00 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
2cc10 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
2cc20 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
2cc30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cc40 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2cc50 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2cc60 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2cc70 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2cc80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2cc90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2cca0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2ccb0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2ccc0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2ccd0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
2cce0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2ccf0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2cd00 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2cd10 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2cd20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2cd30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2cd40 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2cd50 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2cd60 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2cd70 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2cd80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2cd90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cda0 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
2cdb0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2cdc0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2cdd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2cde0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2cdf0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2ce00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2ce10 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2ce20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ce30 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2ce40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2ce50 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2ce60 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2ce70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2ce80 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2ce90 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2cea0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ceb0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2cec0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2ced0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2cee0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2cef0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2cf00 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2cf10 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2cf20 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2cf30 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2cf40 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
2cf50 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
2cf60 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
2cf70 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
2cf80 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
2cf90 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
2cfa0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2cfb0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2cfc0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2cfd0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2cfe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2cff0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2d000 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d010 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2d020 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2d030 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2d040 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
2d050 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2d060 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2d070 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2d080 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2d090 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2d0a0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2d0b0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2d0c0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2d0d0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2d0e0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2d0f0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2d100 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2d110 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2d120 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d130 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2d140 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2d150 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2d160 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2d170 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2d180 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2d190 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2d1a0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2d1b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2d1c0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2d1d0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2d1e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2d1f0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2d200 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2d210 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2d220 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2d230 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2d240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2d250 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2d260 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2d270 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
2d280 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2d290 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2d2a0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2d2b0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
2d2c0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
2d2d0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
2d2e0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
2d2f0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
2d300 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
2d310 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
2d320 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
2d330 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
2d340 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
2d350 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
2d360 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
2d370 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2d380 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2d390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2d3a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d3b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2d3c0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2d3d0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2d3e0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2d3f0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2d400 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2d410 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2d420 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2d430 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2d440 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2d450 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2d460 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2d470 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2d480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d490 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2d4a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2d4b0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2d4c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d4d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2d4e0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2d4f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d500 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2d510 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2d520 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2d530 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2d540 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2d550 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
2d560 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
2d570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2d580 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
2d590 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2d5a0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2d5b0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2d5c0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2d5d0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2d5e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2d5f0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2d600 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
2d610 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2d620 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d630 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
2d640 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
2d650 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d660 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d670 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
2d680 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
2d690 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
2d6a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
2d6b0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
2d6c0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
2d6d0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
2d6e0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2d6f0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
2d700 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2d710 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
2d720 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2d730 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2d740 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2d750 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
2d760 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2d770 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2d780 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2d790 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
2d7a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d7b0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2d7c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2d7d0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2d7e0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2d7f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2d800 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
2d810 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
2d820 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d830 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
2d840 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d850 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
2d860 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d870 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
2d880 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2d890 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
2d8a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d8b0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2d8c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d8d0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2d8e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2d8f0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2d900 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2d910 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d920 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
2d930 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2d940 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d950 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2d960 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2d970 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d980 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
2d990 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2d9a0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
2d9b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2d9c0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
2d9d0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2d9e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
2d9f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2da00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2da10 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2da20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2da30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
2da40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2da50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2da60 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2da70 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2da80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2da90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2daa0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2dab0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2dac0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2dad0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2dae0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2daf0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2db00 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2db10 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2db20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2db30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2db40 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
2db50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2db60 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2db70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2db80 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2db90 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
2dba0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
2dbb0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
2dbc0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2dbd0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
2dbe0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
2dbf0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
2dc00 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
2dc10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dc20 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
2dc30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2dc40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
2dc50 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
2dc60 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
2dc70 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2dc80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dc90 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2dca0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2dcb0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2dcc0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2dcd0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
2dce0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
2dcf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dd00 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
2dd10 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
2dd20 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
2dd30 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
2dd40 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
2dd50 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
2dd60 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
2dd70 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
2dd80 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
2dd90 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
2dda0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
2ddb0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
2ddc0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
2ddd0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
2dde0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
2ddf0 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
2de00 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
2de10 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2de20 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
2de30 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2de40 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
2de50 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
2de60 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
2de70 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
2de80 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
2de90 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
2dea0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
2deb0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
2dec0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
2ded0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
2dee0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
2def0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2df00 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
2df10 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
2df20 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
2df30 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
2df40 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
2df50 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2df60 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
2df70 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
2df80 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
2df90 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
2dfa0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
2dfb0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
2dfc0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
2dfd0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
2dfe0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
2dff0 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
2e000 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
2e010 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2e020 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2e030 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2e040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2e050 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
2e060 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
2e070 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
2e080 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
2e090 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
2e0a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
2e0b0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
2e0c0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
2e0d0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
2e0e0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
2e0f0 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
2e100 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
2e110 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
2e120 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
2e130 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
2e140 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
2e150 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
2e160 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
2e170 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
2e180 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
2e190 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
2e1a0 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
2e1b0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
2e1c0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
2e1d0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
2e1e0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
2e1f0 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
2e200 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
2e210 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
2e220 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2e230 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
2e240 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
2e250 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
2e260 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
2e270 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
2e280 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
2e290 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
2e2a0 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
2e2b0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
2e2c0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
2e2d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e2e0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
2e2f0 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
2e300 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
2e310 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
2e320 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
2e330 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
2e340 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
2e350 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
2e360 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
2e370 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
2e380 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e390 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
2e3a0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
2e3b0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
2e3c0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
2e3d0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
2e3e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e3f0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
2e400 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2e410 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
2e420 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
2e430 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
2e440 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
2e450 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
2e460 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
2e470 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
2e480 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
2e490 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
2e4a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
2e4b0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
2e4c0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
2e4d0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
2e4e0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
2e4f0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2e500 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
2e510 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
2e520 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
2e530 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
2e540 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
2e550 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
2e560 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
2e570 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
2e580 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
2e590 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
2e5a0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
2e5b0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
2e5c0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
2e5d0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
2e5e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
2e5f0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
2e600 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
2e610 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
2e620 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2e630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e640 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e650 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
2e660 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
2e670 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
2e680 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
2e690 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
2e6a0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
2e6b0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
2e6c0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
2e6d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e6e0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
2e6f0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
2e700 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
2e710 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
2e720 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
2e730 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
2e740 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
2e750 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
2e760 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
2e770 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e780 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
2e790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2e7a0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
2e7b0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
2e7c0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
2e7d0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
2e7e0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
2e7f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e800 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
2e810 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
2e820 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
2e830 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e840 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2e850 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
2e860 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
2e870 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
2e880 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
2e890 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
2e8a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e8b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
2e8c0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
2e8d0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
2e8e0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
2e8f0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
2e900 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
2e910 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
2e920 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
2e930 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
2e940 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
2e950 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
2e960 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
2e970 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
2e980 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
2e990 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
2e9a0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
2e9b0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
2e9c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2e9d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e9e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2e9f0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
2ea00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ea10 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
2ea20 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2ea30 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2ea40 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2ea50 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
2ea60 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2ea70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ea80 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2ea90 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2eaa0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2eab0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
2eac0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2ead0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2eae0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2eaf0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
2eb00 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2eb10 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2eb20 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
2eb30 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2eb40 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
2eb50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2eb60 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
2eb70 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2eb80 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
2eb90 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2eba0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2ebb0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2ebc0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2ebd0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2ebe0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2ebf0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2ec00 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2ec10 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2ec20 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2ec30 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2ec40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2ec50 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2ec60 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2ec70 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2ec80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2ec90 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2eca0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2ecb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ecc0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2ecd0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2ece0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2ecf0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2ed00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2ed10 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2ed20 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2ed30 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2ed40 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2ed50 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2ed60 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2ed70 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2ed80 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2ed90 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2eda0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2edb0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2edc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2edd0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2ede0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2edf0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2ee00 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2ee10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2ee20 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2ee30 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2ee40 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2ee50 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2ee60 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2ee70 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2ee80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2ee90 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2eea0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2eeb0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2eec0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2eed0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2eee0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2eef0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2ef00 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2ef10 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2ef20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ef30 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2ef40 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2ef50 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2ef60 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2ef70 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2ef80 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2ef90 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2efa0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2efb0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2efc0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2efd0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2efe0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2eff0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2f000 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f010 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2f020 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2f030 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2f040 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2f050 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2f060 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2f070 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2f080 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2f090 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2f0a0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2f0b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2f0c0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2f0d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2f0e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2f0f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2f100 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2f110 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2f120 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2f130 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2f140 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2f150 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2f160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f170 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2f180 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2f190 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2f1a0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2f1b0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2f1c0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2f1d0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2f1e0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2f1f0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2f200 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2f210 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2f220 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2f230 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2f240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2f250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2f260 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2f270 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2f280 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2f290 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2f2a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2f2b0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2f2c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2f2d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f2e0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2f2f0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2f300 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2f310 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2f320 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2f330 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2f340 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2f350 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2f360 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2f370 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2f380 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2f390 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2f3a0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2f3b0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2f3c0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2f3d0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2f3e0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2f3f0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2f400 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2f410 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2f420 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2f430 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2f440 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2f450 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2f460 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f470 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2f480 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2f490 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2f4a0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2f4b0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2f4c0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2f4d0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2f4e0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2f4f0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2f500 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2f510 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2f520 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2f530 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2f540 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2f550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2f560 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2f570 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2f580 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2f590 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2f5a0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2f5b0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2f5c0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2f5d0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2f5e0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2f5f0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2f600 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2f610 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2f620 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2f630 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2f640 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2f650 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2f660 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2f670 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2f680 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2f690 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2f6a0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2f6b0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
2f6c0 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
2f6d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
2f6e0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
2f6f0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
2f700 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
2f710 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
2f720 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2f730 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
2f740 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
2f750 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
2f760 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2f770 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2f780 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2f790 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
2f7a0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
2f7b0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
2f7c0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
2f7d0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
2f7e0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
2f7f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2f800 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2f810 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2f820 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2f830 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2f840 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2f850 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2f860 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2f870 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2f880 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2f890 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2f8a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2f8b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
2f8c0 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
2f8d0 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
2f8e0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
2f8f0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
2f900 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
2f910 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
2f920 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
2f930 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2f940 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
2f950 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
2f960 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
2f970 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
2f980 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
2f990 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
2f9a0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
2f9b0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2f9c0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
2f9d0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
2f9e0 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
2f9f0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
2fa00 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
2fa10 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
2fa20 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
2fa30 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
2fa40 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
2fa50 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2fa60 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2fa70 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2fa80 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
2fa90 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
2faa0 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
2fab0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
2fac0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
2fad0 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
2fae0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
2faf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2fb00 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
2fb10 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
2fb20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
2fb30 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
2fb40 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
2fb50 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
2fb60 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2fb70 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2fb80 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
2fb90 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
2fba0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
2fbb0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2fbc0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2fbd0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
2fbe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fbf0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
2fc00 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
2fc10 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
2fc20 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
2fc30 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
2fc40 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2fc50 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
2fc60 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
2fc70 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
2fc80 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
2fc90 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
2fca0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
2fcb0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2fcc0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
2fcd0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
2fce0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
2fcf0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
2fd00 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2fd10 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2fd20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
2fd30 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
2fd40 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
2fd50 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2fd60 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2fd70 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
2fd80 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
2fd90 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2fda0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2fdb0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
2fdc0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
2fdd0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
2fde0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
2fdf0 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
2fe00 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
2fe10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
2fe20 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
2fe30 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
2fe40 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
2fe50 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
2fe60 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
2fe70 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
2fe80 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
2fe90 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
2fea0 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
2feb0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
2fec0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2fed0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2fee0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2fef0 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
2ff00 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
2ff10 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
2ff20 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
2ff30 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
2ff40 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  d..*/.SQLITE_EXT
2ff50 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
2ff60 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
2ff70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ff80 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
2ff90 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
2ffa0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
2ffb0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
2ffc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2ffd0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
2ffe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fff0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
30000 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
30010 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
30020 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
30030 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
30040 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
30050 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
30060 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
30070 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
30080 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
30090 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
300a0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
300b0 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
300c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
300d0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
300e0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
300f0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
30100 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
30110 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
30120 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
30130 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
30140 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
30150 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
30160 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
30170 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
30180 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
30190 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
301a0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
301b0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
301c0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
301d0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
301e0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
301f0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
30200 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
30210 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
30220 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
30230 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
30240 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
30250 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
30260 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
30270 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
30280 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
30290 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
302a0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
302b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
302c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
302d0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
302e0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
302f0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
30300 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
30310 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
30320 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
30330 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
30340 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
30350 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
30360 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
30370 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
30380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30390 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
303a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
303b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
303c0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
303d0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
303e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
303f0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
30400 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30410 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
30420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
30430 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
30440 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
30450 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
30460 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
30470 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
30480 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
30490 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
304a0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
304b0 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
304c0 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
304d0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
304e0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
304f0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
30500 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
30510 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
30530 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
30540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
30550 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
30560 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30570 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
30580 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
30590 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
305a0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
305b0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
305c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
305d0 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
305e0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
305f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
30600 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
30610 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
30620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30630 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
30640 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
30650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
30660 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
30670 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
30680 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
30690 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
306a0 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
306b0 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
306c0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
306d0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
306e0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
306f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
30700 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
30710 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
30720 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
30730 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
30740 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
30750 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
30760 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
30770 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
30780 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
30790 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
307a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
307b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
307c0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
307d0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
307e0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
307f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
30800 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
30810 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30820 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30830 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30840 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30850 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
30860 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
30870 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
30880 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
30890 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
308a0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
308b0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
308c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
308d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
308e0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
308f0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
30900 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
30910 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
30920 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
30930 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
30940 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
30950 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
30960 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
30970 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
30980 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
30990 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
309a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
309b0 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
309c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
309d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
309e0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
309f0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
30a00 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
30a10 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
30a20 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
30a30 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
30a40 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
30a50 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
30a60 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
30a70 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
30a80 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
30a90 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
30aa0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
30ab0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
30ac0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
30ad0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
30ae0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
30af0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
30b00 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
30b10 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
30b20 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
30b30 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
30b40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30b50 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
30b60 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
30b70 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
30b80 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
30b90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
30ba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
30bb0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
30bc0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
30bd0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
30be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
30bf0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
30c00 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
30c10 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
30c20 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
30c30 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
30c40 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
30c50 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
30c60 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
30c70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30c80 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
30c90 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
30ca0 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
30cb0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
30cc0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
30cd0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
30ce0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
30cf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30d00 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
30d10 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
30d20 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
30d30 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
30d40 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
30d50 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
30d60 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
30d70 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
30d80 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
30d90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
30da0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
30db0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
30dc0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
30dd0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
30de0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
30df0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
30e00 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
30e10 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
30e20 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
30e30 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
30e40 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
30e50 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
30e60 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
30e70 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
30e80 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
30e90 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
30ea0 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
30eb0 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
30ec0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
30ed0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
30ee0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
30ef0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
30f00 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
30f10 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
30f20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
30f30 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
30f40 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
30f50 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
30f60 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
30f70 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
30f80 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
30f90 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
30fa0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
30fb0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
30fc0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
30fd0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
30fe0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
30ff0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
31000 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
31010 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
31020 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
31030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
31040 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
31050 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
31060 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
31070 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
31080 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
31090 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
310a0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
310b0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
310c0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
310d0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
310e0 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
310f0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
31100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
31110 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
31120 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
31130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31140 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
31150 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
31160 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
31170 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
31180 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31190 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
311a0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
311b0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
311c0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
311d0 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
311e0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
311f0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
31200 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
31210 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
31220 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
31230 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
31240 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
31250 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
31260 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rridden..**.** ^
31270 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
31280 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
31290 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
312a0 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
312b0 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
312c0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
312d0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68   deleted..** ^Th
312e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
312f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
31300 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
31310 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
31320 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
31330 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
31340 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c   ^The second cal
31350 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
31360 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
31370 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
31380 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
31390 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
313a0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
313b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
313c0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
313d0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
313e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
313f0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
31400 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
31410 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
31420 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
31430 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
31440 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
31450 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
31460 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54  ected row..** ^T
31470 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
31480 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
31490 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
314a0 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68  e row..** ^In th
314b0 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
314c0 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
314d0 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74   [rowid] after t
314e0 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
314f0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  place..**.** ^(T
31500 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
31510 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
31520 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
31530 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
31540 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
31550 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
31560 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
31570 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  e).)^.**.** ^In 
31580 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
31590 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20  ementation, the 
315a0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
315b0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
315c0 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72  en duplication r
315d0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
315e0 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a  because of an.**
315f0 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20   [ON CONFLICT | 
31600 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c  ON CONFLICT REPL
31610 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e  ACE] clause.  ^N
31620 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65  or is the update
31630 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64   hook.** invoked
31640 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64   when rows are d
31650 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65  eleted using the
31660 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
31670 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  ization]..** The
31680 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69   exceptions defi
31690 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61  ned in this para
316a0 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e  graph might chan
316b0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
316c0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
316d0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ite..**.** The u
316e0 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65  pdate hook imple
316f0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
31700 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
31710 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
31720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
31730 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
31740 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61  invoked the upda
31750 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63  te hook.  Any ac
31760 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
31770 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
31780 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
31790 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
317a0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
317b0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
317c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
317d0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
317e0 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65  gered the update
317f0 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74   hook..** Note t
31800 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
31810 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
31820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31830 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
31840 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
31850 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
31860 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
31870 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
31880 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
31890 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
318a0 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  te_hook(D,C,P) f
318b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72  unction.** retur
318c0 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  ns the P argumen
318d0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
318e0 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74  ous call.** on t
318f0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
31900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
31910 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
31920 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f  the first call o
31930 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  n D..**.** See a
31940 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
31950 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 2c  _commit_hook()],
31960 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
31970 63 6b 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a 20 61  ck_hook()],.** a
31980 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 75  nd [sqlite3_preu
31990 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
319a0 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces..*/.voi
319b0 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
319c0 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
319d0 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
319e0 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
319f0 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
31a00 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
31a10 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
31a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31a30 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
31a40 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
31a50 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  Cache.** KEYWORD
31a60 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
31a70 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  }.**.** ^(This r
31a80 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
31a90 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
31aa0 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
31ab0 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
31ac0 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
31ad0 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
31ae0 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
31af0 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63  nection | connec
31b00 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65  tions].** to the
31b10 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
31b20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
31b30 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
31b40 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e  nt is true.** an
31b50 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
31b60 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61  e argument is fa
31b70 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  lse.)^.**.** ^Ca
31b80 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
31b90 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
31ba0 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
31bb0 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  e process..** Th
31bc0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
31bd0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
31be0 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
31bf0 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
31c00 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
31c10 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
31c20 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
31c30 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
31c40 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ately..**.** ^(T
31c50 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
31c60 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
31c70 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
31c80 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
31c90 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
31ca0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
31cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
31cc0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
31cd0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
31ce0 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
31cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
31d00 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
31d10 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
31d20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
31d30 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
31d40 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
31d50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
31d60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31d70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
31d80 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
31d90 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
31da0 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
31db0 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
31dc0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
31dd0 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a  d otherwise.)^.*
31de0 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63  *.** ^Shared cac
31df0 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
31e00 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
31e10 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
31e20 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
31e30 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
31e40 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
31e50 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
31e60 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
31e70 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
31e80 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
31e90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f  ..**.** See Also
31ea0 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65  :  [SQLite Share
31eb0 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f  d-Cache Mode].*/
31ec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
31ed0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
31ee0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
31ef0 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
31f00 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
31f10 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
31f20 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
31f30 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
31f40 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
31f50 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
31f60 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
31f70 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
31f80 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
31f90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
31fa0 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
31fb0 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
31fc0 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
31fd0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
31fe0 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
31ff0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
32000 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
32010 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
32020 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
32030 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
32040 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
32050 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
32060 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
32070 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
32080 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
32090 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
320a0 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
320b0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
320c0 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
320d0 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
320e0 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
320f0 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
32100 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
32110 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
32120 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
32130 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32140 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
32150 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32160 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
32170 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
32180 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
32190 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
321a0 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61  imit64() interfa
321b0 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71  ce sets and/or q
321c0 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f  ueries the.** so
321d0 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  ft limit on the 
321e0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
321f0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
32200 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
32210 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74  QLite..** ^SQLit
32220 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65  e strives to kee
32230 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74  p heap memory ut
32240 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20  ilization below 
32250 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a  the soft heap.**
32260 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69   limit by reduci
32270 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ng the number of
32280 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74   pages held in t
32290 68 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a  he page cache.**
322a0 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   as heap memory 
322b0 75 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65  usages approache
322c0 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  s the limit..** 
322d0 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c  ^The soft heap l
322e0 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62  imit is "soft" b
322f0 65 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75  ecause even thou
32300 67 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65  gh SQLite strive
32310 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c  s to stay.** bel
32320 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74  ow the limit, it
32330 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65   will exceed the
32340 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68   limit rather th
32350 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61  an generate.** a
32360 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
32370 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65   error.  In othe
32380 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66  r words, the sof
32390 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a  t heap limit .**
323a0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
323b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  y..**.** ^The re
323c0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
323d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
323e0 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74  p_limit64() is t
323f0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68  he size of.** th
32400 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32410 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  t prior to the c
32420 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72  all.  ^If the ar
32430 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61  gument N is nega
32440 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20  tive.** then no 
32450 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74  change is made t
32460 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  o the soft heap 
32470 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74  limit.  Hence, t
32480 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69  he current.** si
32490 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68  ze of the soft h
324a0 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65  eap limit can be
324b0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69   determined by i
324c0 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
324d0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
324e0 69 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65  it64() with a ne
324f0 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e  gative argument.
32500 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
32510 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72  rgument N is zer
32520 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20  o then the soft 
32530 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69  heap limit is di
32540 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  sabled..**.** ^(
32550 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
32560 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72  mit is not enfor
32570 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65  ced in the curre
32580 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
32590 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d  n.** if one or m
325a0 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  ore of following
325b0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20   conditions are 
325c0 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  true:.**.** <ul>
325d0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66  .** <li> The sof
325e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
325f0 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20  set to zero..** 
32600 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f  <li> Memory acco
32610 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c  unting is disabl
32620 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69  ed using a combi
32630 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  nation of the.**
32640 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32650 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
32660 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
32670 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65  ,...) start-time
32680 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20   option and.**  
32690 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f      the [SQLITE_
326a0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
326b0 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  S] compile-time 
326c0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  option..** <li> 
326d0 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70  An alternative p
326e0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
326f0 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63  entation is spec
32700 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  ified using.**  
32710 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
32720 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
32730 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29  FIG_PCACHE],...)
32740 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61  ..** <li> The pa
32750 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74  ge cache allocat
32760 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20  es from its own 
32770 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70  memory pool supp
32780 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20  lied.**      by 
32790 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
327a0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
327b0 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20  PAGECACHE],...) 
327c0 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20  rather than.**  
327d0 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61      from the hea
327e0 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  p..** </ul>)^.**
327f0 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  .** Beginning wi
32800 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
32810 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66  n 3.7.3, the sof
32820 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
32830 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61  enforced.** rega
32840 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
32850 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
32860 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
32870 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a  RY_MANAGEMENT].*
32880 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
32890 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ption is invoked
328a0 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f  .  With [SQLITE_
328b0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
328c0 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68  NAGEMENT],.** th
328d0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
328e0 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e  t is enforced on
328f0 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   every memory al
32900 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f  location.  Witho
32910 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  ut.** [SQLITE_EN
32920 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
32930 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66  GEMENT], the sof
32940 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
32950 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  only enforced.**
32960 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
32970 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65  allocated by the
32980 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65   page cache.  Te
32990 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74  sting suggests t
329a0 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74  hat because.** t
329b0 68 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73  he page cache is
329c0 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65   the predominate
329d0 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20   memory user in 
329e0 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20  SQLite, most.** 
329f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c  applications wil
32a00 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61  l achieve adequa
32a10 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  te soft heap lim
32a20 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77  it enforcement w
32a30 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73  ithout.** the us
32a40 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e of [SQLITE_ENA
32a50 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
32a60 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  EMENT]..**.** Th
32a70 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
32a80 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69  under which SQLi
32a90 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20  te will enforce 
32aa0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32ab0 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67  mit may.** chang
32ac0 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
32ad0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
32ae0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
32af0 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  4 sqlite3_soft_h
32b00 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69  eap_limit64(sqli
32b10 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f  te3_int64 N);../
32b20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
32b30 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48  eprecated Soft H
32b40 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66  eap Limit Interf
32b50 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ace.** DEPRECATE
32b60 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  D.**.** This is 
32b70 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72  a deprecated ver
32b80 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  sion of the [sql
32b90 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32ba0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74  imit64()].** int
32bb0 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f  erface.  This ro
32bc0 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65  utine is provide
32bd0 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
32be0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
32bf0 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77  * only.  All new
32c00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
32c10 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20  ould use the.** 
32c20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
32c30 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e  ap_limit64()] in
32c40 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74  terface rather t
32c50 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f  han this one..*/
32c60 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32c70 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
32c80 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
32c90 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int N);.../*.** 
32ca0 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63  CAPI3REF: Extrac
32cb0 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
32cc0 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
32cd0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  able.**.** ^This
32ce0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
32cf0 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20   metadata about 
32d00 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
32d10 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a  n of a specific.
32d20 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  ** database tabl
32d30 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
32d40 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ng the [database
32d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
32d60 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  dle.** passed as
32d70 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
32d80 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
32d90 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20  .** ^The column 
32da0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
32db0 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
32dc0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
32dd0 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74  rameters to.** t
32de0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54  his function. ^T
32df0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
32e00 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
32e10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
32e20 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
32e30 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
32e40 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
32e50 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
32e60 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
32e70 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
32e80 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55  LL. ^If it is NU
32e90 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
32ea0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
32eb0 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
32ec0 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
32ed0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
32ee0 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74  orithm used by t
32ef0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
32f00 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65  ne to.** resolve
32f10 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
32f20 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
32f30 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
32f40 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
32f50 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
32f60 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
32f70 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a  able and column.
32f80 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
32f90 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
32fa0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
32fb0 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
32fc0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20  rameters.** may 
32fd0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
32fe0 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75  Metadata is retu
32ff0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
33000 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
33010 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
33020 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64  s the 5th.** and
33030 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
33040 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
33050 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66  unction. ^Any of
33060 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73   these arguments
33070 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c   may be.** NULL,
33080 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
33090 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
330a0 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
330b0 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e  data is omitted.
330c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71  .**.** ^(<blockq
330d0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
330e0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
330f0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
33100 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
33110 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
33120 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
33130 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
33140 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
33150 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
33160 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
33170 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
33180 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
33190 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
331a0 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
331b0 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
331c0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
331d0 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
331e0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
331f0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
33200 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
33210 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
33220 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
33230 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
33240 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
33250 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
33260 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
33270 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
33280 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
33290 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
332a0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
332b0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  ^The memory poin
332c0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
332d0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
332e0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
332f0 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e  e.** declaration
33300 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
33310 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
33320 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
33330 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c   the next.** cal
33340 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20  l to any SQLite 
33350 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  API function..**
33360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
33370 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
33380 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
33390 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
333a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
333b0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
333c0 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
333d0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
333e0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
333f0 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
33400 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
33410 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
33420 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
33430 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
33440 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
33450 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
33460 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
33470 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74  d column. ^(If t
33480 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
33490 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
334a0 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  d [INTEGER PRIMA
334b0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20  RY KEY] column, 
334c0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
334d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
334e0 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73  e set as follows
334f0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
33500 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
33510 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
33520 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33530 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
33540 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
33550 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
33560 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
33570 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
33580 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
33590 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
335a0 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
335b0 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
335c0 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
335d0 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
335e0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
335f0 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
33600 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
33610 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
33620 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
33630 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72  found, an [error
33640 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
33650 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
33660 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20  message left.** 
33670 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
33680 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f   connection] (to
33690 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
336a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
336b0 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  sg()).)^.**.** ^
336c0 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
336d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
336e0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
336f0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
33700 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
33710 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
33720 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
33730 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
33740 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33750 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
33760 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
33770 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
33780 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
33790 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
337a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
337b0 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
337c0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
337d0 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
337e0 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
337f0 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
33800 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
33810 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
33820 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
33830 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
33840 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
33850 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
33860 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
33870 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
33880 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
33890 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
338a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
338b0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
338c0 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20  *pNotNull,      
338d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
338e0 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e  T: True if NOT N
338f0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65  ULL constraint e
33900 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a  xists */.  int *
33910 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20  pPrimaryKey,    
33920 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
33930 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
33940 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20   part of PK */. 
33950 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20   int *pAutoinc  
33960 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33970 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
33980 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69  column is auto-i
33990 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a  ncrement */.);..
339a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
339b0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
339c0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  n.**.** ^This in
339d0 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e  terface loads an
339e0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
339f0 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74  n library from t
33a00 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a  he named file..*
33a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33a20 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
33a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
33a40 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
33a50 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e  .** SQLite exten
33a60 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
33a70 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
33a80 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  le zFile..**.** 
33a90 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74  ^The entry point
33aa0 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a   is zProc..** ^z
33ab0 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69  Proc may be 0, i
33ac0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
33ad0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
33ae0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61  ry point.** defa
33af0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
33b00 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
33b10 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33b20 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
33b30 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33b40 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
33b50 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
33b60 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  nd [SQLITE_ERROR
33b70 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  ] if something g
33b80 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49  oes wrong..** ^I
33b90 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
33ba0 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
33bb0 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
33bc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  e.** [sqlite3_lo
33bd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
33be0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
33bf0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69  attempt to.** fi
33c00 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
33c10 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  h error message 
33c20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
33c30 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65  emory.** obtaine
33c40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
33c50 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63  malloc()]. The c
33c60 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a  alling function.
33c70 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  ** should free t
33c80 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
33c90 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
33ca0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45  ree()]..**.** ^E
33cb0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33cc0 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
33cd0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
33ce0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
33cf0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
33d00 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
33d10 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77  s API,.** otherw
33d20 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c  ise an error wil
33d30 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
33d40 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
33d50 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
33d60 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  n() SQL function
33d70 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33d80 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
33d90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
33da0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61            /* Loa
33db0 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  d the extension 
33dc0 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61  into this databa
33dd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f  se connection */
33de0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33df0 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65  File,    /* Name
33e00 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c   of the shared l
33e10 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ibrary containin
33e20 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20  g extension */. 
33e30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72   const char *zPr
33e40 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20  oc,    /* Entry 
33e50 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20  point.  Derived 
33e60 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20  from zFile if 0 
33e70 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
33e80 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75  rMsg       /* Pu
33e90 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  t error message 
33ea0 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f  here if not 0 */
33eb0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33ec0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
33ed0 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  isable Extension
33ee0 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e   Loading.**.** ^
33ef0 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65  So as not to ope
33f00 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73  n security holes
33f10 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63   in older applic
33f20 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a  ations that are.
33f30 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f  ** unprepared to
33f40 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e   deal with exten
33f50 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e  sion loading, an
33f60 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20  d as a means of 
33f70 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74  disabling.** ext
33f80 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77  ension loading w
33f90 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
33fa0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
33fb0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
33fc0 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64  API.** is provid
33fd0 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b  ed to turn the [
33fe0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
33ff0 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e  ension()] mechan
34000 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a  ism on and off..
34010 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
34020 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20   loading is off 
34030 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20  by default. See 
34040 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
34050 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74   ^Call the sqlit
34060 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
34070 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
34080 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
34090 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65  .** to turn exte
340a0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e  nsion loading on
340b0 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
340c0 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
340d0 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66  rn.** it back of
340e0 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20  f again..*/.int 
340f0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
34100 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
34110 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
34120 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
34130 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69  PI3REF: Automati
34140 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69  cally Load Stati
34150 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74  cally Linked Ext
34160 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
34170 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
34180 75 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50  uses the xEntryP
34190 6f 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  oint() function 
341a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
341b0 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64  r.** each new [d
341c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
341d0 6f 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61  on] that is crea
341e0 74 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68  ted.  The idea h
341f0 65 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78  ere is that.** x
34200 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20  EntryPoint() is 
34210 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
34220 66 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79  for a statically
34230 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65   linked SQLite e
34240 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74  xtension.** that
34250 20 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61   is to be automa
34260 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69  tically loaded i
34270 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61  nto all new data
34280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
34290 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74  ..**.** ^(Even t
342a0 68 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69  hough the functi
342b0 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f  on prototype sho
342c0 77 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f  ws that xEntryPo
342d0 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e  int() takes.** n
342e0 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  o arguments and 
342f0 72 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51  returns void, SQ
34300 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e  Lite invokes xEn
34310 74 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20  tryPoint() with 
34320 74 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  three.** argumen
34330 74 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61  ts and expects a
34340 6e 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  nd integer resul
34350 74 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e  t as if the sign
34360 61 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20  ature of the.** 
34370 65 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72  entry point wher
34380 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
34390 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
343a0 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  <pre>.** &nbsp; 
343b0 20 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74   int xEntryPoint
343c0 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73  (.** &nbsp;    s
343d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26  qlite3 *db,.** &
343e0 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63  nbsp;    const c
343f0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a  har **pzErrMsg,.
34400 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
34410 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
34420 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a  3_api_routines *
34430 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b  pThunk.** &nbsp;
34440 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f    );.** </pre></
34450 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
34460 0a 2a 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72  .** If the xEntr
34470 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65  yPoint routine e
34480 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72  ncounters an err
34490 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61  or, it should ma
344a0 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  ke *pzErrMsg.** 
344b0 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72  point to an appr
344c0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
344d0 73 73 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20  ssage (obtained 
344e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
344f0 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64  rintf()]).** and
34500 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f   return an appro
34510 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
34520 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e  de].  ^SQLite en
34530 73 75 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72  sures that *pzEr
34540 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20  rMsg.** is NULL 
34550 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74  before calling t
34560 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
34570 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
34580 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74  invoke.** [sqlit
34590 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70  e3_free()] on *p
345a0 7a 45 72 72 4d 73 67 20 61 66 74 65 72 20 78 45  zErrMsg after xE
345b0 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
345c0 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a  rns.  ^If any.**
345d0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
345e0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c  eturns an error,
345f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
34600 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
34610 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
34620 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
34630 32 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70  2()] call that p
34640 72 6f 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74  rovoked the xEnt
34650 72 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66  ryPoint() will f
34660 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ail..**.** ^Call
34670 69 6e 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  ing sqlite3_auto
34680 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69  _extension(X) wi
34690 74 68 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e  th an entry poin
346a0 74 20 58 20 74 68 61 74 20 69 73 20 61 6c 72 65  t X that is alre
346b0 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69  ady.** on the li
346c0 73 74 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20  st of automatic 
346d0 65 78 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20  extensions is a 
346e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20  harmless no-op. 
346f0 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  ^No entry point.
34700 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  ** will be calle
34710 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
34720 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
34730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
34740 61 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  at is opened..**
34750 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
34760 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
34770 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  o_extension()]..
34780 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
34790 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
347a0 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74  id (*xEntryPoint
347b0 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a  )(void));../*.**
347c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
347d0 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
347e0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
347f0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
34800 63 65 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20  ce disables all 
34810 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
34820 69 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a  ions previously.
34830 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 75 73  ** registered us
34840 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  ing [sqlite3_aut
34850 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  o_extension()]..
34860 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
34870 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
34880 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  sion(void);../*.
34890 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
348a0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
348b0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
348c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
348d0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
348e0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
348f0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
34900 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
34910 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
34920 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
34930 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
34940 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
34950 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
34960 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
34970 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
34980 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
34990 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
349a0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
349b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
349c0 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
349d0 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
349e0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
349f0 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
34a00 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20  Structures used 
34a10 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  by the virtual t
34a20 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  able interface.*
34a30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
34a40 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71   sqlite3_vtab sq
34a50 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65  lite3_vtab;.type
34a60 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
34a70 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71  e3_index_info sq
34a80 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
34a90 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
34aa0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
34ab0 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61  rsor sqlite3_vta
34ac0 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65  b_cursor;.typede
34ad0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
34ae0 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f  _module sqlite3_
34af0 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  module;../*.** C
34b00 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
34b10 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a   Table Object.**
34b20 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
34b30 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75  e3_module {virtu
34b40 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d  al table module}
34b50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .**.** This stru
34b60 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73  cture, sometimes
34b70 20 63 61 6c 6c 65 64 20 61 20 22 76 69 72 74 75   called a "virtu
34b80 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
34b90 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
34ba0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34bb0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
34bc0 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
34bd0 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
34be0 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
34bf0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
34c00 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
34c10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
34c20 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
34c30 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
34c40 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
34c50 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
34c60 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
34c70 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
34c80 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
34c90 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
34ca0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
34cb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
34cc0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
34cd0 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
34ce0 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
34cf0 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
34d00 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
34d10 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
34d20 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
34d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34d40 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
34d50 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
34d60 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
34d70 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
34d80 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
34d90 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
34da0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
34db0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
34dc0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
34dd0 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
34de0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
34df0 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
34e00 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
34e10 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
34e20 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
34e30 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
34e40 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
34e50 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
34e60 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
34e70 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
34e80 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
34e90 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
34ea0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
34eb0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
34ec0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34ed0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
34ee0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
34ef0 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
34f00 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
34f10 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
34f20 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
34f30 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
34f40 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
34f50 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
34f60 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
34f70 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
34f80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
34f90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
34fa0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
34fb0 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
34fc0 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
34fd0 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
34fe0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
34ff0 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
35000 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35010 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
35020 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
35030 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
35040 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
35050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
35060 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
35070 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
35080 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
35090 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
350a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
350b0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
350c0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
350d0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
350e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
350f0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
35100 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
35110 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
35120 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
35130 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
35140 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
35150 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
35160 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
35170 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
35180 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
35190 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
351a0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
351b0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
351c0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
351d0 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
351e0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
351f0 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
35200 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35210 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
35220 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
35230 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
35240 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
35250 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
35260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35270 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
35280 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35290 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
352a0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
352b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
352c0 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
352d0 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
352e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
352f0 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
35300 72 20 2a 7a 4e 65 77 29 3b 0a 20 20 2f 2a 20 54  r *zNew);.  /* T
35310 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
35320 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
35330 30 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  0 of the sqlite_
35340 6d 6f 64 75 6c 65 20 6f 62 6a 65 63 74 2e 20 54  module object. T
35350 68 6f 73 65 20 0a 20 20 2a 2a 20 62 65 6c 6f 77  hose .  ** below
35360 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
35370 20 31 20 61 6e 64 20 67 72 65 61 74 65 72 2e 20   1 and greater. 
35380 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 61 76 65  */.  int (*xSave
35390 70 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76  point)(sqlite3_v
353a0 74 61 62 20 2a 70 56 54 61 62 2c 20 69 6e 74 29  tab *pVTab, int)
353b0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6c 65 61  ;.  int (*xRelea
353c0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
353d0 20 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20   *pVTab, int);. 
353e0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
353f0 54 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  To)(sqlite3_vtab
35400 20 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 7d   *pVTab, int);.}
35410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35420 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
35430 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d   Indexing Inform
35440 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44  ation.** KEYWORD
35450 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  S: sqlite3_index
35460 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _info.**.** The 
35470 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
35480 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  fo structure and
35490 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72   its substructur
354a0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 70 61  es is used as pa
354b0 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  rt.** of the [vi
354c0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74  rtual table] int
354d0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73  erface to.** pas
354e0 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
354f0 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
35500 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
35510 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a  e [xBestIndex].*
35520 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76  * method of a [v
35530 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
35540 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64  ule].  The field
35550 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
35560 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
35570 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
35580 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
35590 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
355a0 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
355b0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
355c0 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
355d0 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  elds..**.** ^(Th
355e0 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
355f0 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
35600 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
35610 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
35620 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  rm:.**.** <block
35630 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20  quote>column OP 
35640 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  expr</blockquote
35650 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50  >.**.** where OP
35660 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74   is =, &lt;, &lt
35670 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74  ;=, &gt;, or &gt
35680 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72  ;=.)^  ^(The par
35690 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72  ticular operator
356a0 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e   is.** stored in
356b0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f   aConstraint[].o
356c0 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  p using one of t
356d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
356e0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
356f0 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  Q | SQLITE_INDEX
35700 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c  _CONSTRAINT_ val
35710 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  ues].)^.** ^(The
35720 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
35730 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
35740 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74  n.** aConstraint
35750 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e  [].iColumn.)^  ^
35760 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75  (aConstraint[].u
35770 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
35780 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
35790 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
357a0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
357b0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
357c0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
357d0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
357e0 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
357f0 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ot.)^.**.** ^The
35800 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d   optimizer autom
35810 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73  atically inverts
35820 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f   terms of the fo
35830 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75  rm "expr OP colu
35840 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73  mn".** and makes
35850 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63   other simplific
35860 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48  ations to the WH
35870 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e  ERE clause in an
35880 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67   attempt to.** g
35890 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45  et as many WHERE
358a0 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
358b0 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77  to the form show
358c0 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69  n above as possi
358d0 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f  ble..** ^The aCo
358e0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
358f0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
35900 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
35910 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c   that are.** rel
35920 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72  evant to the par
35930 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
35940 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
35950 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f  ied..**.** ^Info
35960 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
35970 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
35980 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
35990 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45  OrderBy[]..** ^E
359a0 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
359b0 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
359c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
359d0 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
359e0 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e  .** The [xBestIn
359f0 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74  dex] method must
35a00 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
35a10 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
35a20 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
35a30 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
35a40 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
35a50 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76  ilter.  ^If argv
35a60 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20  Index>0 then.** 
35a70 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
35a80 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65  ide of the corre
35a90 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72  sponding aConstr
35aa0 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61  aint[] is evalua
35ab0 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d  ted.** and becom
35ac0 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78  es the argvIndex
35ad0 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67  -th entry in arg
35ae0 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72  v.  ^(If aConstr
35af0 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
35b00 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
35b10 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
35b20 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
35b30 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
35b40 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
35b50 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
35b60 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
35b70 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a   by SQLite.)^.**
35b80 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20  .** ^The idxNum 
35b90 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
35ba0 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
35bb0 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nd passed into t
35bc0 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20  he.** [xFilter] 
35bd0 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c  method..** ^[sql
35be0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
35bf0 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78  used to free idx
35c00 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  Ptr if and only 
35c10 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65  if.** needToFree
35c20 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a  IdxPtr is true..
35c30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72  **.** ^The order
35c40 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73  ByConsumed means
35c50 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f   that output fro
35c60 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65  m [xFilter]/[xNe
35c70 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  xt] will occur i
35c80 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
35c90 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
35ca0 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
35cb0 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
35cc0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
35cd0 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
35ce0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
35cf0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
35d00 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
35d10 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
35d20 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
35d30 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
35d40 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
35d50 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
35d60 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
35d70 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
35d80 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
35d90 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
35da0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
35db0 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
35dc0 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
35dd0 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
35de0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
35df0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
35e00 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
35e10 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
35e20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
35e30 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
35e40 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
35e50 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
35e60 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
35e70 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
35e80 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
35e90 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
35ea0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
35eb0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
35ec0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
35ed0 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
35ee0 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
35ef0 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
35f00 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
35f10 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
35f20 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
35f30 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
35f40 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
35f50 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
35f60 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
35f70 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
35f80 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
35f90 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
35fa0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
35fb0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
35fc0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
35fd0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
35fe0 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
35ff0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
36000 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
36010 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
36020 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
36030 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
36040 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
36050 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
36060 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
36070 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
36080 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
36090 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
360a0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
360b0 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
360c0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
360d0 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
360e0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
360f0 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
36100 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36110 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
36120 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
36130 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
36140 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
36150 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
36160 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
36170 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
36180 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
36190 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
361a0 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
361b0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
361c0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
361d0 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20  intUsage;.  int 
361e0 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20  idxNum;         
361f0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
36200 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66   used to identif
36210 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20  y the index */. 
36220 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20   char *idxStr;  
36230 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
36240 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20  tring, possibly 
36250 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
36260 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a  lite3_malloc */.
36270 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
36280 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20  IdxStr;      /* 
36290 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e  Free idxStr usin
362a0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
362b0 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e   if true */.  in
362c0 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  t orderByConsume
362d0 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  d;       /* True
362e0 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c   if output is al
362f0 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f  ready ordered */
36300 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61  .  double estima
36310 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a  tedCost;      /*
36320 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20   Estimated cost 
36330 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e  of using this in
36340 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  dex */.};../*.**
36350 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
36360 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72 61  al Table Constra
36370 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f 64  int Operator Cod
36380 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  es.**.** These m
36390 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74 68  acros defined th
363a0 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  e allowed values
363b0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   for the.** [sql
363c0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d  ite3_index_info]
363d0 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f  .aConstraint[].o
363e0 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20 76  p field.  Each v
363f0 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73 0a  alue represents.
36400 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20 74  ** an operator t
36410 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
36420 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72 6d   constraint term
36430 20 69 6e 20 74 68 65 20 77 48 45 52 45 20 63 6c   in the wHERE cl
36440 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65  ause of.** a que
36450 72 79 20 74 68 61 74 20 75 73 65 73 20 61 20 5b  ry that uses a [
36460 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
36470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36480 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
36490 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
364a0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
364b0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
364c0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
364d0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
364e0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
364f0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
36500 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
36510 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
36520 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36530 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
36540 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36550 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
36560 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
36570 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
36580 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
36590 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  Implementation.*
365a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
365b0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
365c0 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
365d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
365e0 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20  odule] name..** 
365f0 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75  ^Module names mu
36600 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
36610 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74   before.** creat
36620 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ing a new [virtu
36630 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20  al table] using 
36640 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62  the module and b
36650 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a  efore using a.**
36660 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69   preexisting [vi
36670 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72  rtual table] for
36680 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
36690 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e  ** ^The module n
366a0 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ame is registere
366b0 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  d on the [databa
366c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
366d0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
366e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
366f0 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f  er.  ^The name o
36700 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20  f the module is 
36710 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a  given by the .**
36720 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
36730 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  r.  ^The third p
36740 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
36750 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  inter to.** the 
36760 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
36770 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
36780 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20  able module].   
36790 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70  ^The fourth.** p
367a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
367b0 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20  rbitrary client 
367c0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
367d0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
367e0 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ugh.** into the 
367f0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
36800 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
36810 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
36820 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20  table module.** 
36830 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75  when a new virtu
36840 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62  al table is be b
36850 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20  eing created or 
36860 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a  reinitialized..*
36870 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36880 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
36890 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68  v2() interface h
368a0 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d  as a fifth param
368b0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
368c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
368d0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
368e0 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20  he pClientData. 
368f0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a   ^SQLite will.**
36900 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
36910 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
36920 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  (if it is not NU
36930 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a  LL) when SQLite.
36940 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  ** no longer nee
36950 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  ds the pClientDa
36960 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  ta pointer.  ^Th
36970 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
36980 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69 6e 76  l also.** be inv
36990 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
369a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
369b0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 66  te_module_v2() f
369c0 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ails..** ^The sq
369d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
369e0 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ule().** interfa
369f0 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
36a00 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
36a10 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77  te_module_v2() w
36a20 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65  ith a NULL.** de
36a30 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74  structor..*/.int
36a40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36a50 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
36a60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36a70 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
36a80 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
36a90 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
36aa0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
36ab0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
36ac0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
36ad0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
36ae0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
36af0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
36b00 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
36b10 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
36b20 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20  ientData        
36b30 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
36b40 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
36b50 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20  nnect */.);.int 
36b60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36b70 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69  odule_v2(.  sqli
36b80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36b90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
36ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
36bb0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
36bc0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
36bd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
36be0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36bf0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
36c00 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
36c10 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
36c20 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
36c30 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
36c40 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20  ClientData,     
36c50 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
36c60 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
36c70 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69  Connect */.  voi
36c80 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
36c90 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c  d*)     /* Modul
36ca0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
36cb0 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ction */.);../*.
36cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
36cd0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61  tual Table Insta
36ce0 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  nce Object.** KE
36cf0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
36d00 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  vtab.**.** Every
36d10 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
36d20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
36d30 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
36d40 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69  bclass.** of thi
36d50 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63  s object to desc
36d60 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
36d70 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
36d80 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
36d90 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
36da0 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
36db0 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
36dc0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
36dd0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
36de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
36df0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
36e00 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
36e10 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
36e20 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
36e30 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
36e40 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
36e50 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
36e60 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c  ** ^Virtual tabl
36e70 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
36e80 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
36e90 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
36ea0 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
36eb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36ec0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
36ed0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
36ee0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
36ef0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
36f00 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
36f10 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
36f20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36f30 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
36f40 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
36f50 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
36f60 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74  rrMsg.  ^After t
36f70 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
36f80 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
36f90 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
36fa0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
36fb0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
36fc0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
36fd0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
36fe0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
36ff0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
37000 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
37010 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37020 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
37030 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
37040 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
37050 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
37060 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
37070 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
37080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37090 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
370a0 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
370b0 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
370c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
370d0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
370e0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
370f0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
37100 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
37110 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
37120 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
37130 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
37140 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
37150 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
37160 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
37170 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
37180 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37190 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62  sor {virtual tab
371a0 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a  le cursor}.**.**
371b0 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
371c0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
371d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
371e0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
371f0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
37200 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
37210 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37220 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37230 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  he.** [virtual t
37240 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73  able] and are us
37250 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
37260 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
37270 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
37280 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
37290 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
372a0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e  te3_module.xOpen
372b0 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64   | xOpen] method
372c0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61   of the module a
372d0 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  nd are destroyed
372e0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69  .** by the [sqli
372f0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73  te3_module.xClos
37300 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68  e | xClose] meth
37310 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  od.  Cursors are
37320 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
37330 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78  [xFilter], [xNex
37340 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f  t], [xEof], [xCo
37350 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77  lumn], and [xRow
37360 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  id] methods.** o
37370 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
37380 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
37390 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
373a0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
373b0 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
373c0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
373d0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
373e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
373f0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
37400 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
37410 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
37420 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
37430 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
37440 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37450 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
37460 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
37470 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
37480 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
37490 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
374a0 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
374b0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
374c0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
374d0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
374e0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
374f0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
37500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37510 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65  Declare The Sche
37520 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20  ma Of A Virtual 
37530 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Table.**.** ^The
37540 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
37550 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
37560 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75  s of a.** [virtu
37570 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
37580 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72   call this inter
37590 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61  face.** to decla
375a0 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74  re the format (t
375b0 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74  he names and dat
375c0 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f  atypes of the co
375d0 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65  lumns) of.** the
375e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
375f0 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a  they implement..
37600 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
37610 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69  eclare_vtab(sqli
37620 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
37630 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20   *zSQL);../*.** 
37640 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f  CAPI3REF: Overlo
37650 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f  ad A Function Fo
37660 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
37670 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61  e.**.** ^(Virtua
37680 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
37690 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
376a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
376b0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
376c0 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e   using the [xFin
376d0 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f  dFunction] metho
376e0 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  d of the [virtua
376f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
37700 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c    .** But global
37710 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f   versions of tho
37720 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
37730 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72  must exist in or
37740 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f  der to be overlo
37750 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  aded.)^.**.** ^(
37760 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73  This API makes s
37770 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72  ure a global ver
37780 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69  sion of a functi
37790 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63  on with a partic
377a0 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64  ular.** name and
377b0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
377c0 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49  eters exists.  I
377d0 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69  f no such functi
377e0 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66  on exists.** bef
377f0 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20  ore this API is 
37800 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75  called, a new fu
37810 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  nction is create
37820 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65  d.)^  ^The imple
37830 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
37840 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
37850 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
37860 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
37870 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
37880 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
37890 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
378a0 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
378b0 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
378c0 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
378d0 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
378e0 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
378f0 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
37900 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
37910 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e  al table]..*/.in
37920 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
37930 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
37940 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
37950 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
37960 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
37970 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
37980 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
37990 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
379a0 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
379b0 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
379c0 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
379d0 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
379e0 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
379f0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
37a00 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
37a10 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
37a20 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37a30 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
37a40 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
37a50 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
37a60 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
37a70 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
37a80 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
37a90 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
37aa0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
37ab0 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
37ac0 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
37ad0 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
37ae0 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
37af0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
37b00 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
37b10 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
37b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
37b30 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
37b40 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44   BLOB.** KEYWORD
37b50 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d  S: {BLOB handle}
37b60 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a   {BLOB handles}.
37b70 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
37b80 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
37b90 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
37ba0 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63  pen BLOB on whic
37bb0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  h.** [sqlite3_bl
37bc0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
37bd0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
37be0 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
37bf0 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66  ..** ^Objects of
37c00 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63   this type are c
37c10 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
37c20 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
37c30 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  ** and destroyed
37c40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
37c50 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e  b_close()]..** ^
37c60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
37c70 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
37c80 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
37c90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  e()] interfaces.
37ca0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
37cb0 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
37cc0 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e  small subsection
37cd0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a  s of the BLOB..*
37ce0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
37cf0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
37d00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37d10 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
37d20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a  BLOB in bytes..*
37d30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
37d40 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71   sqlite3_blob sq
37d50 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a  lite3_blob;../*.
37d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
37d70 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63  n A BLOB For Inc
37d80 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a  remental I/O.**.
37d90 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
37da0 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c  aces opens a [BL
37db0 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64  OB handle | hand
37dc0 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  le] to the BLOB 
37dd0 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f  located.** in ro
37de0 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a  w iRow, column z
37df0 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54  Column, table zT
37e00 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65  able in database
37e10 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65   zDb;.** in othe
37e20 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d  r words, the sam
37e30 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c  e BLOB that woul
37e40 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79  d be selected by
37e50 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
37e60 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c       SELECT zCol
37e70 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61  umn FROM zDb.zTa
37e80 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64  ble WHERE [rowid
37e90 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70  ] = iRow;.** </p
37ea0 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  re>)^.**.** ^If 
37eb0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
37ec0 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
37ed0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   then the BLOB i
37ee0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
37ef0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
37f00 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73  ccess. ^If it is
37f10 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20   zero, the BLOB 
37f20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
37f30 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  ad access..** ^I
37f40 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
37f50 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
37f60 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
37f70 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70  of an index or p
37f80 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66  rimary .** key f
37f90 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20  or writing. ^If 
37fa0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
37fb0 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e  straints] are en
37fc0 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a  abled, it is .**
37fd0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
37fe0 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74   open a column t
37ff0 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
38000 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72   [child key] for
38010 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   writing..**.** 
38020 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64  ^Note that the d
38030 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
38040 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  not the filename
38050 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a   that contains.*
38060 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  * the database b
38070 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79  ut rather the sy
38080 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74  mbolic name of t
38090 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
380a0 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65  .** appears afte
380b0 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64  r the AS keyword
380c0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
380d0 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20  se is connected 
380e0 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a  using [ATTACH]..
380f0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e  ** ^For the main
38100 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
38110 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
38120 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20  e is "main"..** 
38130 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73  ^For TEMP tables
38140 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
38150 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a  ame is "temp"..*
38160 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73  *.** ^(On succes
38170 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
38180 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74  s returned and t
38190 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e  he new [BLOB han
381a0 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a  dle] is written.
381b0 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f  ** to *ppBlob. O
381c0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
381d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
381e0 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62  rned and *ppBlob
381f0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65   is set.** to be
38200 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e   a null pointer.
38210 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  )^.** ^This func
38220 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64  tion sets the [d
38230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38240 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  on] error code a
38250 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
38260 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
38270 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
38280 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
38290 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61  rmsg()] and rela
382a0 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ted.** functions
382b0 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  . ^Note that the
382c0 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c   *ppBlob variabl
382d0 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74  e is always init
382e0 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20  ialized in a.** 
382f0 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69  way that makes i
38300 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65  t safe to invoke
38310 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
38320 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c  lose()] on *ppBl
38330 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ob.** regardless
38340 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20   of the success 
38350 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
38360 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
38370 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74  * ^(If the row t
38380 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c  hat a BLOB handl
38390 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d  e points to is m
383a0 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a  odified by an.**
383b0 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45   [UPDATE], [DELE
383c0 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43  TE], or by [ON C
383d0 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66  ONFLICT] side-ef
383e0 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68  fects.** then th
383f0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
38400 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69   marked as "expi
38410 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73  red"..** This is
38420 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c   true if any col
38430 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69  umn of the row i
38440 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  s changed, even 
38450 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65  a column.** othe
38460 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74  r than the one t
38470 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
38480 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20  s open on.)^.** 
38490 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74  ^Calls to [sqlit
384a0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
384b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
384c0 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a  b_write()] for.*
384d0 2a 20 61 6e 20 65 78 70 69 72 65 64 20 42 4c 4f  * an expired BLO
384e0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
384f0 74 68 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65  th a return code
38500 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
38510 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73  T]..** ^(Changes
38520 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20   written into a 
38530 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68  BLOB prior to th
38540 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20  e BLOB expiring 
38550 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65  are not.** rolle
38560 64 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78  d back by the ex
38570 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  piration of the 
38580 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e  BLOB.  Such chan
38590 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ges will eventua
385a0 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66  lly.** commit if
385b0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
385c0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
385d0 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  mpletion.)^.**.*
385e0 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69  * ^Use the [sqli
385f0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
38600 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64  ] interface to d
38610 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a  etermine the siz
38620 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  e of.** the open
38630 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73  ed blob.  ^The s
38640 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61  ize of a blob ma
38650 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  y not be changed
38660 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65   by this.** inte
38670 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20  rface.  Use the 
38680 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d  [UPDATE] SQL com
38690 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74  mand to change t
386a0 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20  he size of a.** 
386b0 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  blob..**.** ^The
386c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
386d0 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b  eroblob()] and [
386e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
386f0 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72  eroblob()] inter
38700 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65  faces.** and the
38710 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62   built-in [zerob
38720 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  lob] SQL functio
38730 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69  n can be used, i
38740 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f  f desired,.** to
38750 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79   create an empty
38760 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c  , zero-filled bl
38770 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72  ob in which to r
38780 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69  ead or write usi
38790 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  ng.** this inter
387a0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  face..**.** To a
387b0 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20  void a resource 
387c0 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e  leak, every open
387d0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73   [BLOB handle] s
387e0 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79  hould eventually
387f0 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20  .** be released 
38800 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
38810 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
38820 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
38830 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20  te3_blob_open(. 
38840 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e   sqlite3*,.  con
38850 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20  st char *zDb,.  
38860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54