/ Hex Artifact Content
Login

Artifact d7cc9050446a5ed9eb896362dd264e6e10e0cc03:


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 5b 73 71 6c  eter to the [sql
5210: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
5220: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5240: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5250: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5260: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5270: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5280: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5290: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
52a0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
52b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
52c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
52d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
52e0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
52f0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5300: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5310: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5320: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5330: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5340: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5350: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5370: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5380: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
5390: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
53b0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
53c0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
53d0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
53f0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
5400: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
5410: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5420: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5440: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5450: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5460: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5480: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5490: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
54a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
54c0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
54d0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
54e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5500: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
5510: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
5520: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5540: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5550: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5560: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5580: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5590: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
55a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
55c0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
55d0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
55e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
5600: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
5610: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
5620: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5630: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5640: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5650: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5660: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5670: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5680: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5690: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
56a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
56b0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
56c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
56d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
56f0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
5700: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
5710: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5720: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
5740: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
5750: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
5760: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
5770: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
5780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5790: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
57a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
57b0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
57c0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
57d0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
57e0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
57f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
5800: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
5810: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
5820: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
5830: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
5840: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
5850: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
5860: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
5870: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
5880: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
5890: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
58a0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
58b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
58c0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
58d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
58e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
58f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5900: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
5910: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5940: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
5950: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
5960: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
5970: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
5980: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5990: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
59a0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
59b0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
59c0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
59d0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
59f0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
5a00: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
5a10: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5a20: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
5a30: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5a40: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
5a50: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5a60: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
5a70: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
5a80: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5a90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5aa0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
5ab0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5ac0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
5ad0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
5ae0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
5af0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
5b00: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
5b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5b20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
5b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5b40: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5b50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5b60: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
5b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
5ba0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5bb0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5bc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5bd0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
5be0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
5bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5c00: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
5c10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5c20: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
5c30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5c40: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
5c50: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5c70: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5c90: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
5ca0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
5cb0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
5cc0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
5cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ce0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d10: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5d20: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
5d30: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5d40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5d50: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
5d60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
5d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5d80: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
5d90: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
5da0: 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00800../*.** CAP
5db0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
5dc0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
5dd0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
5de0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
5df0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5e00: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
5e10: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
5e20: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
5e30: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
5e40: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
5e50: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
5e60: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
5e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
5e90: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
5ea0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
5eb0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
5ec0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
5ed0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
5ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5ef0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
5f00: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
5f10: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
5f20: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
5f30: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
5f40: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
5f50: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
5f60: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
5f70: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
5f80: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
5f90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5fa0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
5fb0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
5fc0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5fd0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5fe0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
5ff0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
6000: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6010: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
6020: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
6030: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
6040: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
6050: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
6060: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
6070: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
6080: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
6090: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
60a0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
60b0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
60c0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
60d0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
60e0: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
60f0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
6100: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
6110: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
6120: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
6130: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
6140: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
6150: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6160: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
6170: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
6180: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
6190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
61a0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
61b0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
61c0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
61d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
61e0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
61f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
6200: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
6210: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
6220: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
6230: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
6240: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
6250: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
6260: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
6270: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
6280: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
6290: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
62a0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
62b0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
62c0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
62d0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
62e0: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
62f0: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
6300: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
6310: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
6320: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
6330: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
6340: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
6350: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
6360: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
6370: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
6380: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
6390: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
63a0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
63b0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
63c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
63d0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
63e0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
63f0: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
6400: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
6410: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
6420: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
6430: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
6440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6450: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
6460: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
6470: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6480: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6490: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
64a0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
64b0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
64c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
64d0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
64e0: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
64f0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
6500: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
6510: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
6520: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
6530: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
6540: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
6550: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
6560: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
6570: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
6580: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
6590: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
65a0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
65b0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
65c0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
65d0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
65e0: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
65f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
6600: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6610: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
6620: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
6630: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
6640: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
6650: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
6660: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
6670: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6680: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
6690: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
66a0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
66b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
66c0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
66d0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
66e0: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
66f0: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
6700: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6710: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
6720: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
6730: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
6740: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
6750: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6760: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
6770: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
6780: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6790: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
67a0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
67b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
67c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
67d0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
67e0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
67f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
6800: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
6810: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
6820: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
6830: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
6840: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
6850: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
6860: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
6870: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
6880: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
6890: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
68a0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
68b0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
68c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
68d0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
68e0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
68f0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
6900: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6910: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6920: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
6930: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
6940: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
6950: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
6960: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
6970: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
6980: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
6990: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
69a0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
69b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
69c0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
69d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
69e0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
69f0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
6a00: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
6a10: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
6a20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
6a30: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
6a40: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
6a50: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
6a60: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
6a70: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
6a80: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
6a90: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
6aa0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
6ab0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
6ac0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
6ad0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
6ae0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
6af0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
6b00: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
6b10: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
6b20: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
6b30: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
6b40: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
6b50: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
6b60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
6b70: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6b80: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
6b90: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
6ba0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
6bb0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
6bc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6bd0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6be0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6bf0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6c00: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6c10: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
6c20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c30: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
6c40: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
6c50: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
6c60: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
6c70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
6c80: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
6c90: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
6ca0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
6cb0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
6cc0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
6cd0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
6ce0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
6cf0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
6d00: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
6d10: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
6d20: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
6d30: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
6d40: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
6d50: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
6d60: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
6d70: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
6d80: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
6d90: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
6da0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
6db0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
6dc0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
6dd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
6de0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
6df0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
6e00: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
6e10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6e20: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
6e30: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
6e40: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
6e50: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
6e60: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
6e70: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6e80: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
6e90: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
6ea0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
6eb0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
6ec0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
6ed0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6ee0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6ef0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6f00: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6f10: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6f20: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6f30: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6f40: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6f50: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6f60: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6f70: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
6f80: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6f90: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6fa0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6fb0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6fc0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6fd0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6fe0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6ff0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
7000: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
7010: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
7020: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
7030: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
7040: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
7050: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
7060: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
7070: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
7080: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
7090: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
70a0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
70b0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
70c0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
70d0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
70e0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
70f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7100: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
7110: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
7120: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
7130: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
7140: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
7150: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
7160: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
7170: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
7180: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
7190: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
71a0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
71b0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
71c0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
71d0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
71e0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
71f0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
7200: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
7210: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
7220: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
7230: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7240: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
7250: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
7260: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
7270: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
7280: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
7290: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
72a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
72b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
72c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
72d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
72e0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
72f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
7300: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7310: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7320: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7330: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
7340: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
7360: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7370: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
7380: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
73d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
73e0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
73f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
7410: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
7420: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7430: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
7440: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
7450: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
7460: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
7470: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7480: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
7490: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
74a0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
74b0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
74c0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
74d0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
74e0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
74f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
7500: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
7510: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
7520: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
7530: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
7540: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
7550: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
7560: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
7570: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
7580: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
7590: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
75a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
75b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
75c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
75d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
75e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
75f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7600: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
7610: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
7620: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
7630: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
7640: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
7650: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
7660: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
7670: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
7680: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
7690: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
76a0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
76b0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
76c0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
76d0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
76e0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
76f0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
7700: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
7710: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
7720: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
7730: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
7740: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
7750: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
7760: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
7770: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7780: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
7790: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
77a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
77b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
77c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
77d0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
77e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
77f0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7800: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
7810: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7820: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7830: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
7840: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7850: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
7860: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7870: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7880: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
7890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
78a0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
78b0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
78c0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
78d0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
78e0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
78f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7900: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
7910: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
7920: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
7930: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7940: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
7950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7960: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
7970: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
7980: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7990: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
79a0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
79b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
79c0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
79d0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
79e0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
79f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7a00: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
7a10: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
7a20: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
7a30: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
7a40: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
7a50: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
7a60: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
7a70: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
7a80: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
7a90: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
7aa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
7ab0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7ac0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
7ad0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
7ae0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
7af0: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
7b00: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7b10: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
7b20: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
7b30: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
7b40: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
7b50: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
7b60: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41  sion 2 */.  /* A
7b70: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
7b80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
7b90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
7ba0: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
7bb0: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
7bc0: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
7bd0: 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  pcodes.**.** The
7be0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
7bf0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
7c00: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
7c10: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
7c20: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
7c30: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7c40: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
7c50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7c60: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
7c70: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
7c80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
7c90: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
7ca0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
7cb0: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
7cc0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
7cd0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7ce0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
7cf0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7d00: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
7d10: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
7d20: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
7d30: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7d40: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
7d50: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
7d60: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7d70: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
7d80: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
7d90: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
7da0: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
7db0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
7dc0: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
7dd0: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
7de0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
7df0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
7e00: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
7e10: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
7e20: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  * is defined..**
7e30: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7e40: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
7e50: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
7e60: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
7e70: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
7e80: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
7e90: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
7ea0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
7eb0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
7ec0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
7ed0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
7ee0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
7ef0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
7f00: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
7f10: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
7f20: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
7f30: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
7f40: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
7f50: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7f60: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
7f70: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
7f80: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
7f90: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
7fa0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
7fb0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  faster..**.** Th
7fc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7fd0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
7fe0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
7ff0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
8000: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
8010: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
8020: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
8030: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
8040: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
8050: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
8060: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
8070: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
8080: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
8090: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
80a0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
80b0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
80c0: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
80d0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
80e0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
80f0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
8100: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
8110: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
8120: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
8130: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
8140: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
8150: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
8160: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
8170: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
8180: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
8190: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
81a0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
81b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
81c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
81d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
81e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
81f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8200: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8210: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8220: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8230: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8240: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8250: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8260: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8270: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8280: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
8290: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
82a0: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
82b0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
82c0: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
82d0: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
82e0: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
82f0: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
8300: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
8310: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
8320: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
8330: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
8340: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
8350: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
8360: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
8370: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8380: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
8390: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
83a0: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
83b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
83c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
83d0: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
83e0: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
83f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
8400: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
8410: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
8420: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
8430: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
8440: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
8450: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8460: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
8470: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
8480: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
8490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
84a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
84b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
84c0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
84d0: 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69 6e 65  it.  .*/.#define
84e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
84f0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
8500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8510: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
8520: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
8530: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
8540: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
8550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8560: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
8570: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
8580: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
8590: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35  ZE_HINT        5
85a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
85b0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
85c0: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
85d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
85e0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37  LE_POINTER     7
85f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8600: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8610: 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a  ED     8.../*.**
8620: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
8630: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
8640: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
8650: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
8660: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
8670: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
8680: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
8690: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
86a0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
86b0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
86c0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
86d0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
86e0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
86f0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
8700: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
8710: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
8720: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
8730: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
8740: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
8750: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
8760: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
8770: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8780: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
8790: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
87a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
87b0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
87c0: 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
87d0: 3a 20 56 46 53 20 56 46 53 65 73 0a 2a 2a 0a 2a  : VFS VFSes.**.*
87e0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
87f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
8800: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
8810: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
8820: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
8830: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
8840: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
8850: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
8860: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
8870: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
8880: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
8890: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
88a0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
88b0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
88c0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
88d0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
88e0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
88f0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
8900: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
8910: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
8920: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8930: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
8940: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
8950: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
8960: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
8970: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
8980: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
8990: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
89a0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
89b0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
89c0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
89d0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
89e0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
89f0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
8a00: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
8a10: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
8a20: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
8a30: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
8a40: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
8a50: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
8a60: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
8a70: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
8a80: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
8a90: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
8aa0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
8ab0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
8ac0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
8ad0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
8ae0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
8af0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
8b00: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
8b10: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
8b20: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
8b30: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
8b40: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
8b50: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
8b60: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
8b70: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
8b80: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
8b90: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8ba0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
8bb0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
8bc0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
8bd0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
8be0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
8bf0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
8c00: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
8c10: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
8c20: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
8c30: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
8c40: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
8c50: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
8c60: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
8c70: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
8c80: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
8c90: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
8ca0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
8cb0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
8cc0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
8cd0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
8ce0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
8cf0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
8d00: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
8d10: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
8d20: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
8d30: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
8d40: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
8d50: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
8d60: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
8d70: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
8d80: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
8d90: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
8da0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
8db0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
8dc0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
8dd0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
8de0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
8df0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
8e00: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
8e10: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
8e20: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
8e30: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
8e40: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
8e50: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
8e60: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
8e70: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
8e80: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
8e90: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
8ea0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8eb0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
8ec0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
8ed0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
8ee0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
8ef0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
8f00: 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   10 alphanumeric
8f10: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
8f20: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
8f30: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
8f40: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
8f50: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
8f60: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
8f70: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
8f80: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
8f90: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
8fa0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
8fb0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
8fc0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
8fd0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
8fe0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
8ff0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
9000: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
9010: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
9020: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
9030: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
9040: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9050: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
9060: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
9070: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
9080: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
9090: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
90a0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
90b0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
90c0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
90d0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
90e0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
90f0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
9100: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
9110: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9120: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9130: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
9140: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
9150: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
9160: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
9170: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
9180: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9190: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
91a0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
91b0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
91c0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
91d0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
91e0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
91f0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
9200: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
9210: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
9220: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
9230: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
9240: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
9250: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
9260: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
9270: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
9280: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
9290: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
92a0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
92b0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
92c0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
92d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
92e0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
92f0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
9300: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
9310: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
9320: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
9330: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
9340: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
9350: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
9360: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
9370: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
9380: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
9390: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
93a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
93b0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
93c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
93d0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
93e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
93f0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
9400: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9410: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
9420: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
9430: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
9440: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
9450: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
9460: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
9470: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
9480: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
9490: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
94a0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
94b0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
94c0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
94d0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
94e0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
94f0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
9500: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
9510: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
9520: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
9530: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
9540: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
9550: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
9560: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
9570: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
9580: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
9590: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
95a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
95b0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
95c0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
95d0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
95e0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
95f0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
9600: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
9610: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
9620: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
9630: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
9640: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
9650: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
9660: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
9670: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
9680: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
9690: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
96a0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
96b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
96c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
96d0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
96e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
96f0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
9700: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
9710: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9720: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
9730: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
9740: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
9750: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
9760: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
9770: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
9780: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
9790: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
97a0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
97b0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
97c0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
97d0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
97e0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
97f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
9800: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
9810: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
9820: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
9830: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
9840: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
9850: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
9860: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
9870: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
9880: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
9890: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
98a0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
98b0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
98c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
98d0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
98e0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
98f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
9900: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
9910: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
9920: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
9930: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
9940: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
9950: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
9960: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
9970: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
9980: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
9990: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
99a0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
99b0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
99c0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
99d0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
99e0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
99f0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
9a00: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
9a10: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
9a20: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
9a30: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
9a40: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
9a50: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
9a60: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
9a70: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
9a80: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
9a90: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
9aa0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
9ab0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
9ac0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
9ad0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
9ae0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
9af0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
9b00: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
9b10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9b20: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
9b30: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
9b40: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
9b50: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
9b60: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
9b70: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
9b80: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
9b90: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
9ba0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
9bb0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
9bc0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
9bd0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
9be0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
9bf0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
9c00: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
9c10: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
9c20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9c30: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9c40: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
9c50: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
9c60: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
9c70: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
9c80: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
9c90: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
9ca0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9cb0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9cc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
9cd0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9ce0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
9cf0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
9d00: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
9d10: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9d20: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9d30: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9d40: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
9d50: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
9d60: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
9d70: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
9d80: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
9d90: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
9da0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9db0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9dc0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9dd0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9de0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9df0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9e00: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9e10: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9e20: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9e30: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9e40: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
9e50: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
9e60: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
9e70: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
9e80: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9e90: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9ea0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9eb0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9ec0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9ed0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9ee0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9ef0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9f00: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9f10: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9f20: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9f30: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
9f40: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
9f50: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9f60: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9f70: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9f80: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9f90: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9fa0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9fb0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9fc0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9fd0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9fe0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9ff0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
a000: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
a010: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
a020: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
a030: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
a040: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
a050: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
a060: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
a070: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
a080: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
a090: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
a0a0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
a0b0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
a0c0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
a0d0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
a0e0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
a0f0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
a100: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
a110: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
a120: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
a130: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
a140: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
a150: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a160: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
a170: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
a180: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
a190: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
a1a0: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
a1b0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
a1c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
a1d0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
a1e0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
a1f0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
a200: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
a210: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
a220: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
a230: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
a240: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
a250: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
a260: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
a270: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
a280: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
a290: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
a2a0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
a2b0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
a2c0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
a2d0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
a2e0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
a2f0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
a300: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
a310: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
a320: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
a330: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
a340: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
a350: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a360: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
a370: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
a380: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
a390: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
a3a0: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
a3b0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
a3c0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
a3d0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
a3e0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
a3f0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
a400: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
a410: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
a420: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
a430: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
a440: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
a450: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
a460: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
a470: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
a480: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
a490: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
a4a0: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
a4b0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
a4c0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
a4d0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
a4e0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
a4f0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
a500: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
a510: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
a520: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
a530: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
a540: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
a550: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
a560: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
a570: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
a580: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
a590: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
a5a0: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
a5b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
a5c0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
a5d0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
a5e0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
a5f0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
a600: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
a610: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
a620: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
a630: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
a640: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
a650: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
a660: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
a670: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a680: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
a690: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
a6a0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
a6b0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
a6c0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
a6d0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
a6e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
a6f0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
a700: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
a710: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
a720: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
a730: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
a740: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
a750: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
a760: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
a770: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
a780: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
a790: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
a7a0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
a7b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
a7c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
a7d0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
a7e0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
a7f0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
a800: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
a810: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
a820: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
a830: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
a840: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
a850: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
a860: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
a870: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
a880: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
a890: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a8a0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
a8b0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
a8c0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
a8d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a8e0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
a8f0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
a900: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
a910: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
a920: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
a930: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
a940: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
a950: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
a960: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a970: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
a980: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
a990: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
a9a0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
a9b0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
a9c0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
a9d0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
a9e0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
a9f0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
aa00: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
aa10: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
aa20: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
aa30: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
aa40: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
aa50: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
aa60: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
aa70: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
aa80: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
aa90: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
aaa0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
aab0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
aac0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
aad0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
aae0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
aaf0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
ab00: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ab10: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ab20: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
ab30: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ab40: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
ab50: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
ab60: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
ab70: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
ab80: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
ab90: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
aba0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
abb0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
abc0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
abd0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
abe0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
abf0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
ac00: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ac10: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
ac20: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
ac30: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
ac40: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
ac50: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
ac60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ac70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ac80: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
ac90: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
aca0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
acb0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
acc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
acd0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ace0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
acf0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ad00: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ad10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ad20: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
ad30: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ad40: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ad50: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
ad60: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
ad70: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
ad80: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
ad90: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
ada0: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
adb0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
adc0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
add0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
ade0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
adf0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
ae00: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
ae10: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
ae20: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
ae30: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
ae40: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
ae50: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
ae60: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
ae70: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
ae80: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
ae90: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
aea0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
aeb0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
aec0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
aed0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
aee0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
aef0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
af00: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
af10: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
af20: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
af30: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
af40: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
af50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
af60: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
af70: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
af80: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
af90: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
afa0: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
afb0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
afc0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
afd0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
afe0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
aff0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
b000: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
b010: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
b020: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b030: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
b040: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
b050: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
b060: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
b070: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
b080: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
b090: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
b0a0: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
b0b0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
b0c0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
b0d0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
b0e0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
b0f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
b100: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
b110: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
b120: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
b130: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
b140: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
b150: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
b160: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
b170: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
b180: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
b190: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
b1a0: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
b1b0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
b1c0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
b1d0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
b1e0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
b1f0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
b200: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b210: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
b220: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
b230: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
b240: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
b250: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
b260: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
b270: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
b280: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
b290: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
b2a0: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
b2b0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
b2c0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
b2d0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
b2e0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
b2f0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
b300: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
b310: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
b320: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
b330: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
b340: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
b350: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
b360: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
b370: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
b380: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
b390: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
b3a0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
b3b0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
b3c0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
b3d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
b3e0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b3f0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
b400: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
b410: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
b420: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
b430: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
b440: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
b450: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
b460: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
b470: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
b480: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
b490: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
b4a0: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
b4b0: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
b4c0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
b4d0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
b4e0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
b4f0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
b500: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
b510: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
b520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
b530: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
b540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b550: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
b560: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b570: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
b580: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
b590: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b5a0: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
b5b0: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
b5c0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
b5d0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
b5e0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
b5f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
b600: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
b610: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
b620: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
b630: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
b640: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
b650: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
b660: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
b670: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
b680: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
b690: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
b6a0: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
b6b0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
b6c0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
b6d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
b6e0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
b6f0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
b700: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
b710: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
b720: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
b730: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
b740: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
b750: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b760: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
b770: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
b780: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
b790: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
b7a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b7b0: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
b7c0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
b7d0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
b7e0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
b7f0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
b800: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
b810: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
b820: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
b830: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
b840: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
b850: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
b860: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
b870: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
b880: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
b890: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b8a0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
b8b0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
b8c0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
b8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b8e0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
b8f0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
b900: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
b910: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
b920: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
b930: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
b940: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
b950: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
b960: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
b970: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
b980: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
b990: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
b9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b9b0: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
b9c0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
b9d0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
b9e0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
b9f0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
ba00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
ba10: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
ba20: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
ba30: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ba40: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
ba50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ba60: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
ba70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ba80: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
ba90: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
baa0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
bab0: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
bac0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
bad0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
bae0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
baf0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
bb00: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
bb10: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
bb20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
bb30: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
bb40: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
bb50: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
bb60: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
bb70: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
bb80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
bb90: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
bba0: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
bbb0: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
bbc0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
bbd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bbe0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
bbf0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
bc00: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
bc10: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
bc20: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
bc30: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
bc40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bc50: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
bc60: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
bc70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bc80: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
bc90: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
bca0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
bcb0: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
bcc0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
bcd0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
bce0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
bcf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
bd00: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
bd10: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
bd20: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
bd30: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
bd40: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
bd50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
bd60: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
bd70: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
bd80: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
bd90: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
bda0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
bdb0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
bdc0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
bdd0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
bde0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
bdf0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
be00: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
be10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
be20: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
be30: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
be40: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
be50: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
be60: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
be70: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
be80: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
be90: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
bea0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
beb0: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
bec0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
bed0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
bee0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bef0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
bf00: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
bf10: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
bf20: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
bf30: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
bf40: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
bf50: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
bf60: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
bf70: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
bf80: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
bf90: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
bfa0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
bfb0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
bfc0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
bfd0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
bfe0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
bff0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c000: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
c010: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
c020: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
c030: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c040: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
c050: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
c060: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
c070: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
c080: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
c090: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
c0a0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
c0b0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
c0c0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
c0d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
c0e0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
c0f0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
c100: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
c110: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
c120: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
c130: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
c140: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
c150: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
c160: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
c170: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
c180: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
c190: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
c1a0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
c1b0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
c1c0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
c1d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
c1e0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
c1f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
c200: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
c210: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
c220: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
c230: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c240: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
c250: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
c260: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
c270: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
c280: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
c290: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
c2a0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
c2b0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
c2c0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
c2d0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
c2e0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
c2f0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
c300: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
c310: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
c320: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
c330: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
c340: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
c350: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
c360: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
c370: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
c380: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
c390: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
c3a0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c3b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c3c0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
c3d0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c3e0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
c3f0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
c400: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
c410: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
c420: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
c430: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
c440: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
c450: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
c460: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
c470: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
c480: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
c490: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
c4a0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
c4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
c4c0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
c4d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c4e0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
c4f0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c500: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
c510: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
c520: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
c530: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
c540: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
c550: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
c560: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
c570: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
c580: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
c590: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
c5a0: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
c5b0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
c5c0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
c5d0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
c5e0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
c5f0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
c600: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
c610: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
c620: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
c630: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
c640: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
c650: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
c660: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
c670: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
c680: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
c690: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
c6a0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
c6b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
c6c0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
c6d0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
c6e0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
c6f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
c700: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
c710: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
c720: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
c730: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
c740: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
c750: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
c760: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c770: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
c780: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
c790: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
c7a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
c7b0: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
c7c0: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
c7d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
c7e0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
c7f0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
c800: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
c810: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
c820: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
c830: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
c840: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
c850: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
c860: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
c870: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
c880: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
c890: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
c8a0: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
c8b0: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
c8c0: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
c8d0: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
c8e0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
c8f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
c900: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
c910: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
c920: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
c930: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
c940: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
c950: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
c960: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
c970: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
c980: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
c990: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
c9a0: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
c9b0: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
c9c0: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
c9d0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
c9e0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
c9f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
ca00: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
ca10: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
ca20: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
ca30: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
ca40: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
ca50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ca60: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
ca70: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
ca80: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
ca90: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
caa0: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
cab0: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
cac0: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
cad0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
cae0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
caf0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
cb00: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
cb10: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
cb20: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
cb30: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
cb40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
cb50: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
cb60: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
cb70: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cb80: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
cb90: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
cba0: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
cbb0: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
cbc0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
cbd0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
cbe0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
cbf0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
cc00: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
cc10: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
cc20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
cc30: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
cc40: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
cc50: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
cc60: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
cc70: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
cc80: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
cc90: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
cca0: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
ccb0: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
ccc0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
ccd0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
cce0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
ccf0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
cd00: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
cd10: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
cd20: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
cd30: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
cd40: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
cd50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cd60: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
cd70: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cd80: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
cd90: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
cda0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
cdb0: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
cdc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
cdd0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
cde0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
cdf0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ce00: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
ce10: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
ce20: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
ce30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ce40: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
ce50: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
ce60: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
ce70: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ce80: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
ce90: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
cea0: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
ceb0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
cec0: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
ced0: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
cee0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
cef0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
cf00: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
cf10: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
cf20: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
cf30: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
cf40: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
cf50: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
cf60: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
cf70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
cf80: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
cf90: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
cfa0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
cfb0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
cfc0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
cfd0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
cfe0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
cff0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
d000: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
d010: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
d020: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d030: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
d040: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
d050: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
d060: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
d070: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
d080: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
d090: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
d0a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d0b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
d0c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
d0d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
d0e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
d0f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
d100: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
d110: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
d120: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
d130: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
d140: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
d150: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
d160: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d170: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
d180: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
d190: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
d1a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
d1b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
d1c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
d1d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
d1e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
d1f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
d200: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
d210: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
d220: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
d230: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d240: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
d250: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
d260: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d270: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
d280: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
d290: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
d2a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
d2b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
d2c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
d2d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
d2e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
d2f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
d300: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
d310: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
d320: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
d330: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
d340: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
d350: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
d360: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
d370: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
d380: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d390: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
d3a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
d3b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
d3c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
d3d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
d3e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
d3f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
d400: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
d410: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
d420: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
d430: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
d440: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
d450: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
d460: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
d470: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
d480: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
d490: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
d4a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
d4b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
d4c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
d4d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
d4e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
d4f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
d500: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
d510: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
d520: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
d530: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
d540: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
d550: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
d560: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
d570: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
d580: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
d590: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
d5a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
d5b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
d5c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
d5d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
d5e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
d5f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
d600: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
d610: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
d620: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
d630: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
d640: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
d650: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
d660: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
d670: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
d680: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
d690: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
d6a0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
d6b0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
d6c0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
d6d0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
d6e0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
d6f0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
d700: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
d710: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
d720: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
d730: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
d740: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
d750: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
d760: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
d770: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
d780: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
d790: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
d7a0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
d7b0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
d7c0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
d7d0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
d7e0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
d7f0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
d800: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
d810: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
d820: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
d830: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
d840: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d850: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
d860: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
d870: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
d880: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
d890: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
d8a0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
d8b0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
d8c0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
d8d0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
d8e0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
d8f0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
d900: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
d910: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
d920: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
d930: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
d940: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
d950: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
d960: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
d970: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
d980: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
d990: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
d9a0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
d9b0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
d9c0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
d9d0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d9e0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
d9f0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
da00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
da10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
da20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
da30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
da40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
da50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
da60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
da70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
da80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
da90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
daa0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
dab0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
dac0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
dad0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dae0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
daf0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
db00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
db10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
db20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
db30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
db40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
db50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
db60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
db70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
db80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
db90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
dba0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
dbb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
dbc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
dbd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
dbe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
dbf0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
dc00: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
dc10: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
dc20: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
dc30: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
dc40: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
dc50: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
dc60: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
dc70: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
dc80: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
dc90: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
dca0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
dcb0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
dcc0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
dcd0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
dce0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dcf0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
dd00: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
dd10: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
dd20: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
dd30: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
dd40: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
dd50: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
dd60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
dd70: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
dd80: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
dd90: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
dda0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
ddb0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
ddc0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
ddd0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
dde0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
ddf0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
de00: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
de10: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
de20: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
de30: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
de40: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
de50: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
de60: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
de70: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
de80: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
de90: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
dea0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
deb0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
dec0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
ded0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
dee0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
def0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
df00: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
df10: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
df20: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
df30: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
df40: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
df50: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
df60: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
df70: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
df80: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
df90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
dfa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
dfb0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
dfc0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
dfd0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
dfe0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
dff0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
e000: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
e010: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
e020: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
e030: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e040: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
e050: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
e060: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
e070: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
e080: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
e090: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
e0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
e0b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
e0c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
e0d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
e0e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
e0f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
e100: 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
e110: 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
e120: 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
e130: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
e140: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
e150: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
e160: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
e170: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
e180: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
e190: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
e1a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e1b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
e1c0: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
e1d0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
e1e0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
e1f0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
e200: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
e210: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
e220: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
e230: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
e240: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
e250: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
e260: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
e270: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
e280: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
e290: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
e2a0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
e2b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
e2c0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
e2d0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
e2e0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
e2f0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
e300: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
e310: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
e320: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
e330: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
e340: 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
e350: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
e360: 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
e370: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e380: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
e390: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
e3a0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
e3b0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
e3c0: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
e3d0: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
e3e0: 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
e3f0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
e400: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
e410: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
e420: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
e430: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
e440: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
e450: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
e460: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
e470: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
e480: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e490: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e4a0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e4b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e4c0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e4d0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e4e0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e4f0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
e500: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
e510: 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
e520: 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
e530: 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
e540: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e550: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
e560: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
e570: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e580: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
e590: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
e5a0: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
e5b0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
e5c0: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
e5d0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
e5e0: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
e5f0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
e600: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
e610: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
e620: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
e630: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
e640: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
e650: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
e660: 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
e670: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e680: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
e690: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
e6a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e6b0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
e6c0: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
e6d0: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
e6e0: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
e6f0: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
e700: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
e710: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e720: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
e730: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e740: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
e750: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
e760: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
e770: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
e780: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
e790: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
e7a0: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
e7b0: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
e7c0: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
e7d0: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
e7e0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
e7f0: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
e800: 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
e810: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e820: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e830: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e840: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e850: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e860: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e870: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e880: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
e890: 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
e8a0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e8b0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
e8c0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
e8d0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e8e0: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
e8f0: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
e900: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
e910: 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
e920: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
e930: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
e940: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
e950: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
e960: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
e970: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e980: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e990: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e9a0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
e9b0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
e9c0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
e9d0: 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
e9e0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
e9f0: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
ea00: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
ea10: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
ea20: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
ea30: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
ea40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
ea50: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
ea60: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
ea70: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
ea80: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
ea90: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
eaa0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
eab0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
eac0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
ead0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
eae0: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
eaf0: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
eb00: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eb10: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
eb20: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
eb30: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
eb40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
eb50: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
eb60: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
eb70: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
eb80: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
eb90: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
eba0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
ebb0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
ebc0: 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
ebd0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ebe0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ebf0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ec00: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
ec10: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
ec20: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
ec30: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
ec40: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
ec50: 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
ec60: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
ec70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ec80: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
ec90: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
eca0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
ecb0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
ecc0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
ecd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ece0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ecf0: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
ed00: 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
ed10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
ed20: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
ed30: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
ed40: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ed50: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ed60: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
ed70: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
ed80: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
ed90: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
eda0: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
edb0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
edc0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
edd0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
ede0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
edf0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
ee00: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
ee10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ee20: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
ee30: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
ee40: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
ee50: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
ee60: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
ee70: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
ee80: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
ee90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
eea0: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
eeb0: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
eec0: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
eed0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
eee0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
eef0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ef00: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
ef10: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
ef20: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
ef30: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
ef40: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
ef50: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
ef60: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
ef70: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
ef80: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
ef90: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
efa0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
efb0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
efc0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
efd0: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
efe0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
eff0: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
f000: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
f010: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
f020: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
f030: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
f040: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
f050: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
f060: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
f070: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
f080: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
f090: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
f0a0: 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
f0b0: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f0c0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
f0d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f0e0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
f0f0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
f100: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
f110: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
f120: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
f130: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
f140: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
f150: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
f160: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
f170: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
f180: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
f190: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
f1a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
f1b0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
f1c0: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
f1d0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
f1e0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
f1f0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
f200: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
f210: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
f220: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
f230: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f240: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
f250: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
f260: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
f270: 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
f280: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f290: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
f2a0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
f2b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
f2c0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
f2d0: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
f2e0: 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
f2f0: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
f300: 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
f310: 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
f320: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
f330: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
f340: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
f350: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
f360: 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
f370: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f380: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
f390: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f3a0: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
f3b0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
f3c0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
f3d0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
f3e0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
f3f0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
f400: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
f410: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
f420: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
f430: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
f440: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
f450: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
f460: 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
f470: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
f480: 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
f490: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
f4a0: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
f4b0: 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
f4c0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
f4d0: 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
f4e0: 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
f4f0: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
f500: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
f510: 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
f520: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f530: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
f540: 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
f550: 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
f560: 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
f570: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
f580: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
f590: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
f5a0: 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
f5b0: 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
f5c0: 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
f5d0: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
f5e0: 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
f5f0: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
f600: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
f610: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
f620: 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
f630: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
f640: 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
f650: 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
f660: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
f670: 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
f680: 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
f690: 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
f6a0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
f6b0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
f6c0: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
f6d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
f6e0: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
f6f0: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
f700: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
f710: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
f720: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
f730: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
f740: 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
f750: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f760: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
f770: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
f780: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
f790: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
f7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
f7b0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
f7c0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
f7d0: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
f7e0: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
f7f0: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20  implemenation.  
f800: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
f810: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
f820: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
f830: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
f840: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
f850: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f860: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
f870: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
f880: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e  G_PCACHE option.
f890: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
f8a0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
f8b0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
f8c0: 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
f8d0: 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
f8e0: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
f8f0: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
f900: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
f910: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
f920: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
f930: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
f940: 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
f950: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
f960: 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
f970: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
f980: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
f990: 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
f9a0: 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
f9b0: 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
f9c0: 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
f9d0: 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
f9e0: 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
f9f0: 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
fa00: 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
fa10: 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
fa20: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
fa30: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
fa40: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
fa50: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
fa60: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
fa70: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
fa80: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
fa90: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
faa0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
fab0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
fac0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
fad0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
fae0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
faf0: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
fb00: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
fb10: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
fb20: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
fb30: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
fb40: 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
fb50: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
fb60: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
fb70: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
fb80: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
fb90: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
fba0: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
fbb0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
fbc0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
fbd0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
fbe0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
fbf0: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
fc00: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
fc10: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
fc20: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
fc30: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
fc40: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
fc50: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
fc60: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
fc70: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
fc80: 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
fc90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
fca0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
fcb0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
fcc0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
fcd0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
fce0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
fcf0: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
fd00: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
fd10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
fd20: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
fd30: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
fd40: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
fd50: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
fd60: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fd70: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
fd80: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
fd90: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
fda0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
fdb0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
fdc0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
fdd0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
fde0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
fdf0: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
fe00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
fe10: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
fe20: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
fe30: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
fe40: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
fe50: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
fe60: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
fe70: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
fe80: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
fe90: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
fea0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
feb0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
fec0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
fed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fee0: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
fef0: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
ff00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
ff10: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
ff20: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
ff30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
ff40: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
ff50: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
ff60: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
ff70: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
ff80: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
ff90: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
ffa0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
ffb0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
ffc0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
ffd0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
ffe0: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
fff0: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
10000 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
10010 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
10020 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
10030 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
10040 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
10050 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
10060 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
10070 20 61 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e   at 2^12. Reason
10080 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
10090 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
100a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
100b0 72 65 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32  re 2^5 through 2
100c0 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ^8.</dd>.**.** [
100d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
100e0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
100f0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
10100 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10110 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10120 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10130 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10140 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
10150 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
10160 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
10170 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10180 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
10190 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
101a0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
101b0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
101c0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
101d0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
101e0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
101f0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
10200 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
10210 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
10220 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
10230 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10240 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10250 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
10260 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10270 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
10280 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
10290 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
102a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
102b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
102c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
102d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
102e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
102f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
10300 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
10310 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
10320 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
10330 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
10340 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
10350 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
10360 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
10370 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
10380 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
10390 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
103a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
103b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
103c0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
103d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
103e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
103f0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10400 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10410 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10420 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
10430 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
10440 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
10450 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10460 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
10470 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
10480 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10490 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
104a0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
104b0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
104c0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
104d0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
104e0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
104f0 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
10500 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
10510 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
10520 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
10530 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
10540 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
10550 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
10560 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
10570 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
10580 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10590 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
105a0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
105b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
105c0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
105d0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
105e0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
105f0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
10600 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
10610 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
10620 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
10630 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10640 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
10650 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
10660 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10670 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
10680 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10690 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
106a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
106b0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
106c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
106d0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
106e0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
106f0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
10700 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
10710 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
10720 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10730 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
10740 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
10750 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
10760 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10770 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
10780 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
10790 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
107a0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
107b0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
107c0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
107d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
107e0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
107f0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
10800 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
10810 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
10820 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
10830 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
10840 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
10850 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10860 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
10870 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
10880 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
10890 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
108a0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
108b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
108c0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
108d0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
108e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
108f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
10900 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10910 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  G_PCACHE</dt>.**
10920 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
10930 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
10940 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
10950 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
10960 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
10970 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
10980 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
10990 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
109a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
109b0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
109c0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
109d0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
109e0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
109f0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
10a00 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
10a10 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
10a20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
10a30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10a40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
10a50 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
10a60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
10a70 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
10a80 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
10a90 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
10aa0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
10ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
10ac0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
10ad0 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
10ae0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
10af0 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
10b00 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
10b10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
10b20 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
10b30 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
10b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10b50 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
10b60 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
10b70 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
10b80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
10b90 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
10ba0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
10bb0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
10bc0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
10bd0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
10be0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
10bf0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
10c00 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
10c10 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
10c20 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
10c30 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
10c40 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
10c50 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
10c60 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
10c70 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
10c80 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
10c90 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
10ca0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
10cb0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
10cc0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
10cd0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
10ce0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
10cf0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
10d00 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
10d10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
10d20 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
10d30 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
10d40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
10d50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10d60 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
10d70 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
10d80 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
10d90 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
10da0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
10db0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
10dc0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
10dd0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
10de0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
10df0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
10e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
10e10 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
10e20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
10e30 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
10e40 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
10e50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
10e60 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
10e70 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
10e80 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
10e90 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
10ea0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
10eb0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
10ec0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
10ed0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
10ee0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
10ef0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
10f00 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
10f10 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
10f20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10f30 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
10f40 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10f50 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
10f60 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
10f70 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
10f80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
10f90 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
10fa0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
10fb0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
10fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10fd0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
10fe0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
10ff0 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
11000 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11010 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
11020 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
11030 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
11040 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
11050 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
11060 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
11070 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
11080 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
11090 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
110a0 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69  d. If URI handli
110b0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
110c0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
110d0 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20  names.** passed 
110e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
110f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
11100 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  en_v2()], [sqlit
11110 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
11120 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
11130 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
11140 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
11150 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
11160 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
11170 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
11180 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
11190 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
111a0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
111b0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
111c0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
111d0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
111e0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
111f0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
11200 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
11210 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
11220 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
11230 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
11240 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
11250 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
11260 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  ed. By default, 
11270 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
11280 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
11290 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
112a0 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
112b0 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
112c0 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
112d0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
112e0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
112f0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
11300 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11310 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
11320 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
11330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11340 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
11350 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
11360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11370 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
11380 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
11390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
113a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
113b0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
113c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
113d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
113e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
113f0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
11400 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
11410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11420 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11430 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
11440 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
11450 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
11460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
11470 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
11480 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
11490 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
114a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
114b0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
114c0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
114d0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
114e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
114f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
11500 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
11510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11520 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
11530 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
11540 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
11550 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
11560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11570 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
11580 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
11590 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
115a0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
115b0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
115c0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
115d0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
115e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
115f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
11600 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
11610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11620 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
11630 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
11640 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
11650 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
11660 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11670 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
11680 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
11690 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
116a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
116b0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
116c0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
116d0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
116e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
116f0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
11700 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  * int */../*.** 
11710 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
11720 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
11730 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11740 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
11750 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
11760 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
11770 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
11780 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
11790 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
117a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
117b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
117c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
117d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
117e0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
117f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11800 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11810 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11820 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11830 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11840 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11850 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11860 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11870 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11880 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11890 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
118a0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
118b0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
118c0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
118d0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
118e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
118f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11900 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
11910 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11920 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11930 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
11940 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11950 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
11960 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11970 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
11980 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
11990 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
119a0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
119b0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
119c0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
119d0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
119e0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
119f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
11a00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
11a10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
11a20 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
11a30 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
11a40 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
11a50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
11a60 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
11a70 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
11a80 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
11a90 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
11aa0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
11ab0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
11ac0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
11ad0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
11ae0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
11af0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
11b00 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
11b10 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
11b20 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
11b30 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
11b40 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
11b50 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
11b60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11b70 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
11b80 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
11b90 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
11ba0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
11bb0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
11bc0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
11bd0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
11be0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
11bf0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
11c00 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
11c10 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
11c20 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
11c30 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
11c40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
11c50 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
11c60 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
11c70 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
11c80 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
11c90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11ca0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
11cb0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
11cc0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
11cd0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
11ce0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
11cf0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
11d00 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
11d10 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
11d20 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
11d30 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
11d40 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
11d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
11d60 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
11d70 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
11d80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
11d90 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
11da0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11db0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
11dc0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
11dd0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
11de0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
11df0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
11e00 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
11e10 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
11e20 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
11e30 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
11e40 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
11e50 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
11e60 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
11e70 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
11e80 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
11e90 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
11ea0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
11eb0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
11ec0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
11ed0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
11ee0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11ef0 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
11f00 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11f10 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
11f20 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
11f30 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
11f40 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
11f50 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
11f60 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
11f70 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
11f80 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
11f90 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11fa0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
11fb0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
11fc0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
11fd0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
11fe0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
11ff0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
12000 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
12010 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
12020 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
12030 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
12040 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
12050 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
12060 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
12070 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
12080 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
12090 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
120a0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
120b0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
120c0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
120d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
120e0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
120f0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
12100 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
12110 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
12120 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
12130 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
12140 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
12150 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
12160 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
12170 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12180 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
12190 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
121a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
121b0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
121c0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
121d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
121e0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
121f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
12200 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
12210 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
12220 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
12230 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
12240 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
12250 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
12260 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
12270 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
12280 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
12290 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
122a0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
122b0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
122c0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
122d0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
122e0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
122f0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
12300 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
12310 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
12320 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
12330 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
12340 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
12350 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
12360 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
12370 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
12380 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
12390 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
123a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
123b0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
123c0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
123d0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
123e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
123f0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
12400 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
12410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12420 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
12430 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
12440 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
12450 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12460 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
12470 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
12480 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
12490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
124a0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
124b0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
124c0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
124d0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
124e0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
124f0 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
12500 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
12510 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
12520 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
12530 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
12540 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
12550 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
12560 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
12570 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
12580 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
12590 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
125a0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
125b0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
125c0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
125d0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
125e0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
125f0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
12600 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
12610 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
12620 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
12630 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
12640 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
12650 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
12660 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
12670 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
12680 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
12690 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
126a0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
126b0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
126c0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
126d0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
126e0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
126f0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
12700 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
12710 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
12720 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
12730 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
12740 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
12750 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
12760 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
12770 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
12780 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
12790 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
127a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
127b0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
127c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
127d0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
127e0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
127f0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
12800 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
12810 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
12820 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
12830 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
12840 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
12850 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
12860 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
12870 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
12880 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
12890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
128a0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
128b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
128c0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
128d0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
128e0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
128f0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
12900 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
12910 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
12920 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
12930 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
12940 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
12950 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
12960 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
12970 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
12980 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
12990 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
129a0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
129b0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
129c0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
129d0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
129e0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
129f0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
12a00 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
12a10 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
12a20 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
12a30 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
12a40 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
12a50 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
12a60 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
12a70 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
12a80 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
12a90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
12aa0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
12ab0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
12ac0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
12ad0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
12ae0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
12af0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
12b00 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
12b10 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
12b20 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
12b30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
12b40 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
12b50 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
12b60 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
12b70 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
12b80 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
12b90 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
12ba0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
12bb0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
12bc0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
12bd0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
12be0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
12bf0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
12c00 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
12c10 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
12c20 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
12c30 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
12c40 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
12c50 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
12c60 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
12c70 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
12c80 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
12c90 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
12ca0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
12cb0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
12cc0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
12cd0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
12ce0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
12cf0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
12d00 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
12d10 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
12d20 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
12d30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
12d40 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
12d50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
12d60 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
12d70 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
12d80 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
12d90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
12da0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
12db0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
12dc0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
12dd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
12de0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
12df0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
12e00 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
12e10 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
12e20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
12e30 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
12e40 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
12e50 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
12e60 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
12e70 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
12e80 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
12e90 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
12ea0 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
12eb0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
12ec0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
12ed0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
12ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12ef0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
12f00 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
12f10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12f20 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12f30 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
12f40 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
12f50 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
12f60 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
12f70 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
12f80 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
12f90 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
12fa0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
12fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12fc0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
12fd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12fe0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
12ff0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
13000 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
13010 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
13020 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
13030 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
13040 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
13050 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
13060 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
13070 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
13080 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
13090 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
130a0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
130b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
130c0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
130d0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
130e0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
130f0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
13100 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
13110 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
13120 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
13130 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
13140 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
13150 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
13160 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
13170 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
13180 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
13190 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
131a0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
131b0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
131c0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
131d0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
131e0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
131f0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
13200 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
13210 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
13220 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
13230 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
13240 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
13250 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
13260 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
13270 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
13280 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
13290 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
132a0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
132b0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
132c0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
132d0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
132e0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
132f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
13300 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
13310 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
13320 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
13330 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
13340 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
13350 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
13360 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
13370 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
13380 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
13390 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
133a0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
133b0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
133c0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
133d0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
133e0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
133f0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
13400 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
13410 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
13420 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
13430 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
13440 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
13450 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
13460 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
13470 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
13480 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
13490 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
134a0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
134b0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
134c0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
134d0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
134e0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
134f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
13500 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
13510 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
13520 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
13530 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
13540 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
13550 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
13560 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
13570 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
13580 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
13590 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
135a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
135b0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
135c0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
135d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
135e0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
135f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
13600 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
13610 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
13620 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
13630 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
13640 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
13650 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
13660 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
13670 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
13680 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
13690 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
136a0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
136b0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
136c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
136d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
136e0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
136f0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
13700 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
13710 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
13720 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
13730 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
13740 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
13750 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
13760 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
13770 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
13780 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
13790 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
137a0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
137b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
137c0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
137d0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
137e0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
137f0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
13800 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
13810 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
13820 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
13830 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
13840 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13850 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
13860 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
13870 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
13880 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
13890 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
138a0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
138b0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
138c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
138d0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
138e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
138f0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
13900 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
13910 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
13920 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
13930 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
13940 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
13950 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
13960 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
13970 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
13980 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
13990 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
139a0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
139b0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
139c0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
139d0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
139e0 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
139f0 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
13a00 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
13a10 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
13a20 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
13a30 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
13a40 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
13a50 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
13a60 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
13a70 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
13a80 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
13a90 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
13aa0 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
13ab0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
13ac0 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
13ad0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
13ae0 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
13af0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
13b00 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
13b10 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
13b20 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
13b30 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
13b40 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
13b50 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
13b60 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
13b70 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
13b80 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
13b90 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
13ba0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
13bb0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
13bc0 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
13bd0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
13be0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
13bf0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
13c00 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
13c10 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
13c20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
13c30 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
13c40 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
13c50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
13c60 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
13c70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
13c80 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
13c90 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
13ca0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
13cb0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
13cc0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
13cd0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
13ce0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
13cf0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
13d00 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
13d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13d20 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
13d30 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
13d40 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
13d50 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
13d60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
13d70 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
13d80 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
13d90 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
13da0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
13db0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
13dc0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
13dd0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
13de0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
13df0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
13e00 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
13e10 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
13e20 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
13e30 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
13e40 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
13e50 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
13e60 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
13e70 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
13e80 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
13e90 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
13ea0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
13eb0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
13ec0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
13ed0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
13ee0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
13ef0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
13f00 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
13f10 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
13f20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
13f30 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
13f40 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
13f50 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
13f60 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
13f70 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
13f80 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
13f90 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
13fa0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
13fb0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
13fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13fd0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
13fe0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
13ff0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
14000 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
14010 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
14020 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
14030 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
14040 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
14050 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
14060 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14070 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
14080 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
14090 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
140a0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
140b0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
140c0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
140d0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
140e0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
140f0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
14100 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
14110 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
14120 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
14130 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
14140 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
14150 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
14160 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
14170 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
14180 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
14190 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
141a0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
141b0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
141c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
141d0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
141e0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
141f0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
14200 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
14210 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
14220 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
14230 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
14240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14250 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
14260 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
14270 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
14280 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
14290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
142a0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
142b0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
142c0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
142d0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
142e0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
142f0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
14300 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
14310 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
14320 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
14330 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
14340 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
14350 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
14360 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
14370 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
14380 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
14390 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
143a0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
143b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
143c0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
143d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
143e0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
143f0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
14400 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
14410 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
14420 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
14430 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
14440 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
14450 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
14460 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
14470 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
14480 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
14490 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
144a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
144b0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
144c0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
144d0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
144e0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
144f0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
14500 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
14510 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
14520 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14530 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
14540 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
14550 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
14560 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
14570 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
14580 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
14590 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
145a0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
145b0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
145c0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
145d0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
145e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
145f0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
14600 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
14610 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
14620 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
14630 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
14640 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
14650 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
14660 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
14670 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
14680 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
14690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
146a0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
146b0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
146c0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
146d0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
146e0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
146f0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
14700 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
14710 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
14720 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
14730 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
14740 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
14750 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
14760 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
14770 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
14780 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
14790 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
147a0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
147b0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
147c0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
147d0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
147e0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
147f0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
14800 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
14810 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
14820 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
14830 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
14840 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
14850 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
14860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
14870 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
14880 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
14890 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
148a0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
148b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
148c0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
148d0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
148e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
148f0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
14900 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
14910 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
14920 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
14930 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
14940 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
14950 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
14960 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
14970 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
14980 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
14990 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
149a0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
149b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
149c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
149d0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
149e0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
149f0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
14a00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
14a10 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
14a20 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
14a30 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
14a40 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
14a50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
14a60 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
14a70 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
14a80 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14a90 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
14aa0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
14ab0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
14ac0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
14ad0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
14ae0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14af0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
14b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
14b10 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
14b20 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
14b30 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
14b40 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
14b50 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
14b60 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
14b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
14b80 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
14b90 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
14ba0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
14bb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
14bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14bd0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
14be0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
14bf0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
14c00 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
14c10 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
14c20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
14c30 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
14c40 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
14c50 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
14c60 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
14c70 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
14c80 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
14c90 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
14ca0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
14cb0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
14cc0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
14cd0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
14ce0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
14cf0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
14d00 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
14d10 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
14d20 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
14d30 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
14d40 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
14d50 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
14d60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
14d70 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
14d80 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
14d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
14da0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
14db0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
14dc0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
14dd0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
14de0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
14df0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
14e00 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
14e10 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
14e20 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14e30 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
14e40 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
14e50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14e60 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
14e70 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
14e80 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
14e90 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
14ea0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
14eb0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
14ec0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
14ed0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
14ee0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
14ef0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
14f00 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
14f10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14f20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14f30 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
14f40 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
14f50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
14f60 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
14f70 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
14f80 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
14f90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
14fa0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
14fb0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
14fc0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
14fd0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
14fe0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
14ff0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
15000 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
15010 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
15020 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
15030 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
15040 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
15050 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
15060 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
15070 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
15080 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
15090 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
150a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
150b0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
150c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
150d0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
150e0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
150f0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
15100 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
15110 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
15120 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
15130 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
15140 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
15150 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
15160 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
15170 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
15180 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
15190 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
151a0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
151b0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
151c0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
151d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
151e0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
151f0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
15200 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
15210 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
15220 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
15230 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
15240 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
15250 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
15260 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
15270 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
15280 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
15290 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
152a0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
152b0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
152c0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
152d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
152e0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
152f0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
15300 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
15310 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
15320 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
15330 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
15340 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
15350 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
15360 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
15370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
15380 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
15390 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
153a0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
153b0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
153c0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
153d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
153e0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
153f0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
15400 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
15410 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
15420 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
15430 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
15440 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
15450 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
15460 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
15470 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
15480 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
15490 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
154a0 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
154b0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
154c0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
154d0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
154e0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
154f0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
15500 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
15510 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
15520 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
15530 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
15540 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
15550 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
15560 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
15570 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
15580 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
15590 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
155a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
155b0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
155c0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
155d0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
155e0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
155f0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
15600 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
15610 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
15620 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
15630 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
15640 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
15650 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
15660 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
15670 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
15680 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
15690 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
156a0 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
156b0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
156c0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
156d0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
156e0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
156f0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
15700 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
15710 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
15720 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
15730 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
15740 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
15750 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
15760 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
15770 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
15780 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
15790 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
157a0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
157b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
157c0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
157d0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
157e0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
157f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
15800 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
15810 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
15820 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
15830 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
15840 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15850 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
15860 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
15870 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
15880 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
15890 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
158a0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
158b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
158c0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
158d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
158e0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
158f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
15900 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
15910 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
15920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
15930 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
15940 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
15950 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
15960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15970 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
15980 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
15990 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
159a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
159b0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
159c0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
159d0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
159e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
159f0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
15a00 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
15a10 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
15a20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
15a30 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
15a40 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
15a50 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
15a60 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
15a70 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
15a80 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
15a90 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
15aa0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
15ab0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
15ac0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
15ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
15ae0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
15af0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
15b00 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15b10 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
15b20 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
15b30 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
15b40 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
15b50 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
15b60 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
15b70 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
15b80 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
15b90 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
15ba0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
15bb0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
15bc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15bd0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
15be0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
15bf0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
15c00 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
15c10 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
15c20 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
15c30 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
15c40 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
15c50 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
15c60 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
15c70 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
15c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
15c90 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
15ca0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
15cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
15cc0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
15cd0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
15ce0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
15cf0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
15d00 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
15d10 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
15d20 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15d30 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
15d40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
15d50 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
15d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
15d70 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
15d80 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
15d90 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
15da0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
15db0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15dc0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
15dd0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
15de0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
15df0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
15e00 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
15e10 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
15e20 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
15e30 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
15e40 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
15e50 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
15e60 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
15e70 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
15e80 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
15e90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
15ea0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
15eb0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
15ec0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
15ed0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
15ee0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
15ef0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
15f00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
15f10 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
15f20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
15f30 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
15f40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
15f50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
15f60 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
15f70 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
15f80 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
15f90 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
15fa0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
15fb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
15fc0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
15fd0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
15fe0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
15ff0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
16000 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
16010 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
16020 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
16030 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
16040 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
16050 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
16060 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
16070 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16080 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
16090 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
160a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
160b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
160c0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
160d0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
160e0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
160f0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
16100 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
16110 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
16120 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
16130 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
16140 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
16150 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
16160 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
16170 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
16180 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
16190 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
161a0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
161b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
161c0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
161d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
161e0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
161f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16200 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
16210 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
16220 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
16230 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16240 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
16250 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
16260 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
16270 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
16280 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
16290 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
162a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
162b0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
162c0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
162d0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
162e0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
162f0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
16300 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
16310 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
16320 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
16330 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
16340 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
16350 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
16360 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
16370 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
16380 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16390 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
163a0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
163b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
163c0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
163d0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
163e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
163f0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
16400 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16410 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
16420 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
16430 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
16440 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16450 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
16460 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16470 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
16480 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
16490 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
164a0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
164b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
164c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
164d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
164e0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
164f0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
16500 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
16510 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
16520 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
16530 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
16540 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
16550 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
16560 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
16570 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
16580 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
16590 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
165a0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
165b0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
165c0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
165d0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
165e0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
165f0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
16600 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
16610 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
16620 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
16630 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
16640 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
16650 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
16660 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
16670 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
16680 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
16690 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
166a0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
166b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
166c0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
166d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
166e0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
166f0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
16700 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
16710 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
16720 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
16730 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
16740 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
16750 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
16760 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16770 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
16780 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
16790 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
167a0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
167b0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
167c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
167d0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
167e0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
167f0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
16800 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
16810 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
16820 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
16830 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
16840 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
16850 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
16860 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
16870 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
16880 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
16890 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
168a0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
168b0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
168c0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
168d0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
168e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
168f0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16900 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
16910 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
16920 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
16930 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
16940 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
16950 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
16960 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
16970 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
16980 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
16990 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
169a0 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
169b0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
169c0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
169d0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
169e0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
169f0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
16a00 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
16a10 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
16a20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
16a30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
16a40 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
16a50 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
16a60 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
16a70 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
16a80 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
16a90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
16aa0 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
16ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16ac0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
16ad0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
16ae0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
16af0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
16b00 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
16b10 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
16b20 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
16b30 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
16b40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
16b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16b60 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
16b70 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
16b80 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
16b90 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
16ba0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
16bb0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
16bc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16bd0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
16be0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
16bf0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
16c00 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
16c10 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
16c20 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
16c30 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
16c40 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
16c50 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
16c60 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
16c70 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
16c80 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
16c90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
16ca0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
16cb0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
16cc0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
16cd0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
16ce0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
16cf0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
16d00 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
16d10 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
16d20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
16d30 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
16d40 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
16d50 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
16d60 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
16d70 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
16d80 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
16d90 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
16da0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
16db0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
16dc0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
16dd0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
16de0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
16df0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
16e00 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
16e10 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
16e20 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
16e30 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
16e40 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
16e50 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
16e60 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
16e70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
16e80 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
16e90 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
16ea0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
16eb0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
16ec0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
16ed0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
16ee0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
16ef0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
16f00 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
16f10 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
16f20 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
16f30 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
16f40 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
16f50 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
16f60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
16f70 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
16f80 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
16f90 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
16fa0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
16fb0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
16fc0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
16fd0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
16fe0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
16ff0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
17000 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
17010 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
17020 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
17030 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
17040 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
17050 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
17060 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
17070 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
17080 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
17090 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
170a0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
170b0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
170c0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
170d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
170e0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
170f0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
17100 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
17110 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
17120 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
17130 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
17140 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
17150 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
17160 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
17170 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
17180 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
17190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
171a0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
171b0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
171c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
171d0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
171e0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
171f0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
17200 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
17210 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
17220 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
17230 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
17240 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
17250 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
17260 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
17270 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
17280 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
17290 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
172a0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
172b0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
172c0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
172d0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
172e0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
172f0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
17300 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
17310 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
17320 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
17330 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
17340 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
17350 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
17360 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
17370 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
17380 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
17390 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
173a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
173b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
173c0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
173d0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
173e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
173f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
17400 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
17410 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
17420 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
17430 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17440 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17450 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
17460 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
17470 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
17480 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
17490 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
174a0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
174b0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
174c0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
174d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
174e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
174f0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
17500 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
17510 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
17520 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
17530 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
17540 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
17550 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
17560 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
17570 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
17580 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17590 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
175a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
175b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
175c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
175d0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
175e0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
175f0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
17600 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
17610 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
17620 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
17630 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17640 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
17650 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
17660 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
17670 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
17680 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
17690 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
176a0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
176b0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
176c0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
176d0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
176e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
176f0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
17700 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
17710 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
17720 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
17730 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
17740 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
17750 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
17760 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
17770 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
17780 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
17790 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
177a0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
177b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
177c0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
177d0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
177e0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
177f0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
17800 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
17810 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
17820 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
17830 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
17840 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
17850 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17860 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
17870 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
17880 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17890 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
178a0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
178b0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
178c0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
178d0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
178e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
178f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17900 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
17910 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
17920 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
17930 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
17940 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
17950 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
17960 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
17970 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
17980 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
17990 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
179a0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
179b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
179c0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
179d0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
179e0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
179f0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
17a00 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
17a10 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
17a20 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
17a30 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
17a40 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
17a50 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
17a60 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
17a70 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
17a80 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
17a90 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
17aa0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
17ab0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
17ac0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
17ad0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
17ae0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
17af0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
17b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17b10 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
17b20 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
17b30 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
17b40 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
17b50 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
17b60 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
17b70 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
17b80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
17b90 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
17ba0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
17bb0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
17bc0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
17bd0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
17be0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
17bf0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
17c00 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
17c10 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
17c20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
17c30 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
17c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17c50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
17c60 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
17c70 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
17c80 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
17c90 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
17ca0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
17cb0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
17cc0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
17cd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
17ce0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
17cf0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
17d00 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
17d10 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
17d20 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
17d30 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
17d40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
17d50 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
17d60 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
17d70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
17d80 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
17d90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  inter..**.** ^Ca
17da0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
17db0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
17dc0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
17dd0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
17de0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
17df0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
17e00 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
17e10 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
17e20 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
17e30 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
17e40 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
17e50 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
17e60 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
17e70 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
17e80 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
17e90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
17ea0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
17eb0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
17ec0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
17ed0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
17ee0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
17ef0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
17f00 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
17f10 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
17f20 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
17f30 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
17f40 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
17f50 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
17f60 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
17f70 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
17f80 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
17f90 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
17fa0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
17fb0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
17fc0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
17fd0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
17fe0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
17ff0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
18000 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
18010 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
18020 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
18030 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
18040 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
18050 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
18060 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
18070 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
18080 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
18090 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
180a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
180b0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
180c0 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
180d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
180e0 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
180f0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
18100 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20  ter.)^ ^ If the 
18110 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
18120 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
18130 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
18140 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
18150 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
18160 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
18170 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
18180 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
18190 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
181a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
181b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
181c0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
181d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
181e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
181f0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
18200 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
18210 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
18220 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
18230 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
18240 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
18250 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
18260 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18270 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18280 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
18290 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
182a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
182b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
182c0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
182d0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
182e0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
182f0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
18300 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
18310 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
18320 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
18330 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
18340 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
18350 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
18360 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
18370 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
18380 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
18390 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
183a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
183b0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
183c0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
183d0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
183e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
183f0 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
18400 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
18410 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
18420 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
18430 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
18440 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
18450 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
18460 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
18470 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
18480 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
18490 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
184a0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
184b0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
184c0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
184d0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
184e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
184f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
18500 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
18510 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
18520 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
18530 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
18540 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
18550 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
18560 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
18570 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
18580 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
18590 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
185a0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
185b0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
185c0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
185d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
185e0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
185f0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
18600 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
18610 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69  ed..**.** The Wi
18620 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
18630 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
18640 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
18650 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
18660 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
18670 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
18680 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
18690 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
186a0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
186b0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
186c0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
186d0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
186e0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
186f0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
18700 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
18710 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
18720 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
18730 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
18740 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
18750 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
18760 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
18770 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
18780 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
18790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
187a0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
187b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
187c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
187d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
187e0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
187f0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
18800 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
18810 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
18820 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
18830 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
18840 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18850 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
18860 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
18870 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
18880 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
18890 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
188a0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
188b0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
188c0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
188d0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
188e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
188f0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
18900 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
18910 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
18920 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
18930 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
18940 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
18950 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
18960 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
18970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
18980 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
18990 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
189a0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
189b0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
189c0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
189d0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
189e0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
189f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
18a00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
18a10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
18a20 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
18a30 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
18a40 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
18a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18a60 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
18a70 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
18a80 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
18a90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
18aa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
18ab0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
18ac0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
18ad0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
18ae0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
18af0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
18b00 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
18b10 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
18b20 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
18b30 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
18b40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
18b50 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
18b60 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
18b70 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
18b80 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
18b90 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
18ba0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
18bb0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
18bc0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
18bd0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
18be0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
18bf0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
18c00 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
18c10 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
18c20 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
18c30 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
18c40 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
18c50 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
18c60 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
18c70 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
18c80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
18c90 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
18ca0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
18cb0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
18cc0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
18cd0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
18ce0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
18cf0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
18d00 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
18d10 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
18d20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
18d30 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
18d40 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
18d50 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
18d60 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18d70 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
18d80 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
18d90 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
18da0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
18db0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
18dc0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
18dd0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
18de0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
18df0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
18e00 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
18e10 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
18e20 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
18e30 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
18e40 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
18e50 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
18e60 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
18e70 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
18e80 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
18e90 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
18ea0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
18eb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
18ec0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
18ed0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
18ee0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
18ef0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
18f00 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
18f10 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
18f20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
18f30 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
18f40 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
18f50 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
18f60 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
18f70 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
18f80 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
18f90 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
18fa0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
18fb0 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
18fc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
18fd0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
18fe0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
18ff0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
19000 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
19010 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
19020 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
19030 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
19040 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
19050 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
19060 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
19070 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
19080 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
19090 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
190a0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
190b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
190c0 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
190d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
190e0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
190f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
19100 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
19110 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
19120 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
19130 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
19140 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
19150 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
19160 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
19170 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
19180 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
19190 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
191a0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
191b0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
191c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
191d0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
191e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
191f0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
19200 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
19210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
19220 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
19230 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
19240 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
19250 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19260 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
19270 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
19280 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
19290 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
192a0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
192b0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
192c0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
192d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
192e0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
192f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
19300 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
19310 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
19320 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
19330 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
19340 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
19350 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
19360 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
19370 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
19380 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19390 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
193a0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
193b0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
193c0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
193d0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
193e0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
193f0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
19400 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
19410 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
19420 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
19430 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
19440 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
19450 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
19460 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
19470 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
19480 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
19490 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
194a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
194b0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
194c0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
194d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
194e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
194f0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
19500 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
19510 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
19520 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
19530 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
19540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
19550 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
19560 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
19570 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
19580 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
19590 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
195a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
195b0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
195c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
195d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
195e0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
195f0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
19600 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
19610 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
19620 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
19630 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
19640 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19650 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
19660 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
19670 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
19680 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
19690 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
196a0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
196b0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
196c0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
196d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
196e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
196f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19700 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
19710 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
19720 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
19730 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19740 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
19750 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
19760 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
19770 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
19780 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
19790 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
197a0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
197b0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
197c0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
197d0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
197e0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
197f0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
19800 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
19810 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
19820 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19830 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
19840 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
19850 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
19860 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
19870 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
19880 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
19890 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
198a0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
198b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
198c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
198d0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
198e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
198f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
19900 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
19910 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
19920 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
19930 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
19940 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
19950 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
19960 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
19970 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
19980 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
19990 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
199a0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
199b0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
199c0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
199d0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
199e0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
199f0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
19a00 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
19a10 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
19a20 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
19a30 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
19a40 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
19a50 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
19a60 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
19a70 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
19a80 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
19a90 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
19aa0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
19ab0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
19ac0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
19ad0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
19ae0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
19af0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
19b00 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
19b10 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
19b20 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
19b30 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
19b40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19b50 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
19b60 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
19b70 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
19b80 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
19b90 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
19ba0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
19bb0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
19bc0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
19bd0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
19be0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
19bf0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
19c00 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
19c10 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
19c20 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
19c30 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
19c40 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
19c50 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
19c60 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
19c70 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
19c80 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
19c90 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
19ca0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
19cb0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
19cc0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
19cd0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
19ce0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
19cf0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
19d00 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
19d10 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19d20 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
19d30 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
19d40 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
19d50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
19d60 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
19d70 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
19d80 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
19d90 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
19da0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
19db0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
19dc0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
19dd0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
19de0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
19df0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
19e00 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
19e10 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
19e20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
19e30 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
19e40 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
19e50 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
19e60 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
19e70 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
19e80 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
19e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19ea0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
19eb0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
19ec0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
19ed0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
19ee0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
19ef0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
19f00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
19f10 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
19f20 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
19f30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
19f40 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
19f50 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
19f60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19f70 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
19f80 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
19f90 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
19fa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19fb0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
19fc0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
19fd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
19fe0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
19ff0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1a000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1a010 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1a020 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1a030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1a040 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1a050 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1a060 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1a070 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1a080 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a090 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1a0a0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1a0b0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1a0c0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1a0d0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1a0e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1a0f0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1a100 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1a110 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1a120 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1a130 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1a140 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1a150 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1a160 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1a170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1a180 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1a190 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1a1a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a1b0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1a1c0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1a1d0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1a1e0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1a1f0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1a200 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1a210 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1a220 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1a230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a240 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1a250 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1a260 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1a270 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1a280 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1a290 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1a2a0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1a2b0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1a2c0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1a2d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1a2e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1a2f0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1a300 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1a310 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1a320 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a330 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a340 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1a350 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1a360 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1a370 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1a380 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1a390 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a3a0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1a3b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1a3c0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1a3d0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1a3e0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1a3f0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1a400 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1a410 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1a420 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1a430 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1a440 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1a450 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a460 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1a470 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1a480 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1a490 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1a4a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1a4b0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1a4c0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1a4d0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1a4e0 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1a4f0 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1a500 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1a510 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1a520 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1a530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a540 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1a550 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1a560 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1a570 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1a580 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1a590 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1a5a0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1a5b0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1a5c0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1a5d0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1a5e0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1a5f0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a600 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a610 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1a620 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1a630 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1a640 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1a650 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1a660 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1a670 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1a680 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1a690 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1a6a0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1a6b0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1a6c0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1a6d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1a6e0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1a6f0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1a700 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1a710 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1a720 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1a730 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1a740 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1a750 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1a760 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1a770 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1a780 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1a790 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1a7a0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1a7b0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1a7c0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1a7d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1a7e0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1a7f0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1a800 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1a810 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1a820 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a830 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1a840 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1a850 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1a860 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1a870 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1a880 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1a890 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1a8a0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1a8b0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1a8c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a8d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a8e0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1a8f0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1a900 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1a910 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1a920 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1a930 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1a940 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1a950 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1a960 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1a970 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1a980 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1a990 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a9a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a9b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1a9c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1a9d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1a9e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a9f0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1aa00 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1aa10 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1aa20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1aa30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1aa40 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1aa50 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1aa60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1aa70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1aa80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1aa90 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1aaa0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1aab0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1aac0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aad0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1aae0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1aaf0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ab00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ab10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ab20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ab30 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1ab40 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ab50 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ab60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ab70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ab80 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1ab90 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1aba0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1abb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1abc0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1abd0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1abe0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1abf0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ac00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ac10 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1ac20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1ac30 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1ac40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ac50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ac60 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1ac70 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1ac80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ac90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1aca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1acb0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1acc0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1acd0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ace0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1acf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ad00 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1ad10 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1ad20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ad30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ad40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ad50 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1ad60 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1ad70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ad80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ad90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ada0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1adb0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1adc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1add0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ade0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1adf0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1ae00 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1ae10 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ae20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ae30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ae40 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1ae50 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1ae60 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1ae70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ae80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ae90 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1aea0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1aeb0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1aec0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1aed0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1aee0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1aef0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1af00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1af10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1af20 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1af30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1af40 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1af50 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1af60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1af70 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1af80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1af90 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1afa0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1afb0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1afc0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1afd0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1afe0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1aff0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1b000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b010 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1b020 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1b030 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1b040 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b060 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1b070 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1b080 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1b090 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b0a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b0b0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1b0c0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1b0d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b0e0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1b0f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b100 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1b110 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1b120 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1b130 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b150 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1b160 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1b170 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1b180 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b1a0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1b1b0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1b1c0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1b1d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b1e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b1f0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1b200 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1b210 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1b220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b240 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1b250 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1b260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b270 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b290 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1b2a0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1b2b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1b2c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1b2d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b2e0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1b2f0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1b300 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1b310 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1b320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1b330 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1b340 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1b350 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1b360 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1b370 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1b380 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1b390 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1b3a0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1b3b0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1b3c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1b3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b3e0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1b3f0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1b400 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1b410 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1b420 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1b430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b440 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1b450 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
1b460 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
1b470 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
1b480 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
1b490 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
1b4a0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1b4b0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1b4c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1b4d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
1b4e0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
1b4f0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
1b500 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
1b510 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
1b520 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
1b530 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1b540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
1b550 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
1b560 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
1b570 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1b580 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
1b590 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
1b5a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
1b5b0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
1b5c0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
1b5d0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
1b5e0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
1b5f0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
1b600 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1b610 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1b620 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1b630 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1b640 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1b650 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1b660 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1b670 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
1b680 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
1b690 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1b6a0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1b6b0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1b6c0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1b6d0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1b6e0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
1b6f0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1b700 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
1b710 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1b720 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
1b730 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
1b740 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
1b750 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
1b760 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
1b770 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
1b780 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1b790 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
1b7a0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
1b7b0 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
1b7c0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
1b7d0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
1b7e0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
1b7f0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
1b800 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
1b810 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
1b820 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
1b830 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
1b840 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
1b850 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1b860 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
1b870 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
1b880 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
1b890 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
1b8a0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
1b8b0 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
1b8c0 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
1b8d0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
1b8e0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
1b8f0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1b900 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1b910 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
1b920 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1b930 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1b940 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1b950 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1b960 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1b970 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1b980 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1b990 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1b9a0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1b9b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1b9c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1b9d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1b9e0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1b9f0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1ba00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ba10 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1ba20 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1ba30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1ba40 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1ba50 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1ba60 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1ba70 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1ba80 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1ba90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1baa0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1bab0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1bac0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1bad0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1bae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1baf0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1bb00 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1bb10 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1bb20 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1bb30 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1bb40 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1bb50 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1bb60 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1bb70 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1bb80 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1bb90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1bba0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1bbb0 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
1bbc0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1bbd0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1bbe0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1bbf0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1bc00 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1bc10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1bc20 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1bc30 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1bc40 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1bc50 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1bc60 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1bc70 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1bc80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1bc90 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1bca0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1bcb0 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1bcc0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1bcd0 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1bce0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1bcf0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1bd00 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1bd10 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1bd20 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1bd30 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1bd40 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1bd50 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1bd60 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1bd70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1bd80 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1bd90 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1bda0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1bdb0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1bdc0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1bdd0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1bde0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1bdf0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1be00 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1be10 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1be20 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1be30 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1be40 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1be50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1be60 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1be70 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1be80 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1be90 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1bea0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1beb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1bec0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1bed0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1bee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1bef0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1bf00 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1bf10 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1bf20 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1bf30 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1bf40 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1bf50 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1bf60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1bf70 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1bf80 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1bf90 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
1bfa0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1bfb0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
1bfc0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
1bfd0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1bfe0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
1bff0 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
1c000 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1c010 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1c020 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1c030 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1c040 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1c050 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1c060 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1c070 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1c080 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1c090 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
1c0a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1c0b0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1c0c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1c0d0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1c0e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1c0f0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1c100 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1c110 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1c120 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1c130 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c140 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1c150 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1c160 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1c170 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1c180 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1c190 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1c1a0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
1c1b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1c1c0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1c1d0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1c1e0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1c1f0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1c200 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1c210 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1c220 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
1c230 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
1c240 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1c250 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1c260 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1c270 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1c280 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1c290 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1c2a0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1c2b0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
1c2c0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
1c2d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1c2e0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
1c2f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1c300 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1c310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1c320 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1c330 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1c340 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1c350 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1c360 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1c370 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1c380 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1c390 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1c3a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1c3b0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1c3c0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1c3d0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1c3e0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1c3f0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1c400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c410 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1c420 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1c430 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1c440 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1c450 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1c460 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1c470 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c480 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1c490 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1c4a0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1c4b0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1c4c0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1c4d0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1c4e0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1c4f0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1c500 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1c510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c520 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
1c530 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
1c540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1c550 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1c560 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1c570 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1c580 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1c590 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1c5a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1c5b0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1c5c0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1c5d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1c5e0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
1c5f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1c600 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
1c610 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
1c620 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
1c630 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1c640 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1c650 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1c660 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1c670 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1c680 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1c690 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1c6a0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1c6b0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1c6c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1c6d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c6e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1c6f0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
1c700 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1c710 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1c720 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1c730 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
1c740 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
1c750 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
1c760 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
1c770 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
1c780 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
1c790 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
1c7a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
1c7b0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
1c7c0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
1c7d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1c7e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c7f0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1c800 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
1c810 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1c820 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1c830 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c840 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1c850 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
1c860 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
1c870 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1c880 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1c890 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1c8a0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1c8b0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1c8c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c8d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1c8e0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1c8f0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1c900 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1c910 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1c920 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1c930 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1c940 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1c950 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
1c960 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
1c970 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
1c980 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
1c990 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
1c9a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1c9b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1c9c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1c9d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1c9e0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1c9f0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1ca00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ca10 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1ca20 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1ca30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1ca40 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1ca50 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1ca60 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1ca70 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1ca80 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1ca90 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1caa0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1cab0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1cac0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1cad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cae0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1caf0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1cb00 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1cb10 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1cb20 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1cb30 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1cb40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1cb50 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1cb60 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1cb70 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1cb80 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1cb90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cba0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1cbb0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1cbc0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1cbd0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1cbe0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1cbf0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1cc00 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1cc10 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1cc20 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1cc30 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1cc40 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1cc50 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1cc60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cc70 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1cc80 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1cc90 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1cca0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1ccb0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1ccc0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
1ccd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1cce0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ccf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1cd00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
1cd10 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
1cd20 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
1cd30 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1cd40 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
1cd50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1cd60 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
1cd70 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
1cd80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1cd90 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1cda0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
1cdb0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1cdc0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
1cdd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1cde0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1cdf0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1ce00 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1ce10 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1ce20 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1ce30 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1ce40 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
1ce50 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1ce60 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1ce70 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1ce80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1ce90 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1cea0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1ceb0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1cec0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1ced0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1cee0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1cef0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1cf00 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1cf10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1cf20 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1cf30 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1cf40 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1cf50 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1cf60 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1cf70 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1cf80 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1cf90 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1cfa0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1cfb0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1cfc0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1cfd0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1cfe0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1cff0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1d000 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1d010 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1d020 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1d030 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1d040 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1d050 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1d060 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1d070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d080 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1d090 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
1d0a0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1d0b0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
1d0c0 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
1d0d0 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
1d0e0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
1d0f0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
1d100 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
1d110 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
1d120 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
1d130 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
1d140 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
1d150 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
1d160 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
1d170 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1d180 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
1d190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
1d1a0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 69 73 20 73   flag is.** is s
1d1b0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
1d1c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1d1d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
1d1e0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
1d1f0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
1d200 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
1d210 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
1d220 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
1d230 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d240 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
1d250 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
1d260 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
1d270 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1d280 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
1d290 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1d2a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
1d2b0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
1d2c0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
1d2d0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
1d2e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1d2f0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
1d300 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
1d310 0a 2a 2a 20 69 6e 74 65 70 72 65 74 61 74 69 6f  .** intepretatio
1d320 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1d330 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1d340 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1d350 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1d360 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1d370 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1d380 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1d390 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1d3a0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1d3b0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1d3c0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1d3d0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1d3e0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1d3f0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1d400 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1d410 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1d420 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1d430 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1d440 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1d450 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1d460 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1d470 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1d480 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1d490 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1d4a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1d4b0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1d4c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1d4d0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1d4e0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1d4f0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1d500 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1d510 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1d520 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1d530 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1d540 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1d550 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1d560 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1d570 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1d580 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1d590 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1d5a0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1d5b0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1d5c0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1d5d0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1d5e0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1d5f0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1d600 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1d610 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1d620 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1d630 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1d640 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1d650 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1d660 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1d670 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1d680 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1d690 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1d6a0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1d6b0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1d6c0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1d6d0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1d6e0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1d6f0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1d700 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1d710 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1d720 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1d730 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1d740 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1d750 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1d760 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1d770 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1d780 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1d790 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1d7a0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1d7b0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1d7c0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1d7d0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1d7e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1d7f0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1d800 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1d810 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1d820 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1d830 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1d840 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1d850 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1d860 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1d870 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1d880 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1d890 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1d8a0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1d8b0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1d8c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d8d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1d8e0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1d8f0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1d900 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1d910 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1d920 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1d930 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1d940 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1d950 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1d960 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d970 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1d980 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1d990 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1d9a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1d9b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1d9c0 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a   "ro", "rw" or.*
1d9d0 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74  *     "rwc". Att
1d9e0 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
1d9f0 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
1da00 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72  alue is an error
1da10 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
1da20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
1da30 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
1da40 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1da50 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
1da60 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
1da70 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
1da80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1da90 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
1daa0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
1dab0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
1dac0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
1dad0 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20  epare_v2(). ^If 
1dae0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
1daf0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
1db00 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
1db10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1db20 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
1db30 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
1db40 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
1db50 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
1db60 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1db70 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
1db80 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
1db90 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
1dba0 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
1dbb0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1dbc0 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
1dbd0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1dbe0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
1dbf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1dc00 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  TE. ^If sqlite3_
1dc10 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a  open_v2() is .**
1dc20 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73       used, it is
1dc30 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
1dc40 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
1dc50 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
1dc60 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20  ter that is .** 
1dc70 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63      less restric
1dc80 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
1dc90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1dca0 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20  flags passed as 
1dcb0 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20  the third .**   
1dcc0 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
1dcd0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
1dce0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
1dcf0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
1dd00 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1dd10 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
1dd20 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
1dd30 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
1dd40 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
1dd50 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1dd60 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
1dd70 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1dd80 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
1dd90 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
1dda0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
1ddb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ddc0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
1ddd0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
1dde0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
1ddf0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
1de00 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1de10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1de20 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
1de30 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
1de40 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
1de50 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
1de60 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
1de70 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
1de80 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
1de90 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
1dea0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
1deb0 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
1dec0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
1ded0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1dee0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
1def0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1df00 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
1df10 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
1df20 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1df30 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1df40 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1df50 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
1df60 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
1df70 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1df80 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1df90 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
1dfa0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
1dfb0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
1dfc0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
1dfd0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
1dfe0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
1dff0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
1e000 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1e010 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
1e020 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1e030 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
1e040 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
1e050 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
1e060 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
1e070 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
1e080 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
1e090 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
1e0a0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
1e0b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1e0c0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1e0d0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1e0e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1e0f0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1e100 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
1e110 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1e120 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
1e130 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
1e140 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
1e150 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
1e160 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1e170 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
1e180 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1e190 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
1e1a0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
1e1b0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
1e1c0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1e1d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1e1e0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
1e1f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
1e200 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1e210 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
1e220 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
1e230 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
1e240 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
1e250 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
1e260 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
1e270 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1e280 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
1e290 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
1e2a0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
1e2b0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
1e2c0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
1e2d0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
1e2e0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
1e2f0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
1e300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
1e310 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
1e320 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
1e330 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
1e340 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
1e350 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
1e360 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
1e370 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
1e380 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
1e390 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
1e3a0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
1e3b0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1e3c0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
1e3d0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
1e3e0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1e3f0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1e400 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1e410 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
1e420 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
1e430 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
1e440 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1e450 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
1e460 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
1e470 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
1e480 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
1e490 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
1e4a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1e4b0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
1e4c0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
1e4d0 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
1e4e0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
1e4f0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1e500 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
1e510 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
1e520 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
1e530 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1e540 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
1e550 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1e560 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
1e570 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
1e580 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
1e590 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
1e5a0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
1e5b0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
1e5c0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1e5d0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
1e5e0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
1e5f0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
1e600 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
1e610 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
1e620 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
1e630 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
1e640 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
1e650 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
1e660 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
1e670 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
1e680 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
1e690 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
1e6a0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
1e6b0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
1e6c0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
1e6d0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
1e6e0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
1e6f0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
1e700 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
1e710 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
1e720 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
1e730 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
1e740 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
1e750 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
1e760 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
1e770 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
1e780 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
1e790 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
1e7a0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
1e7b0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
1e7c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1e7d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1e7e0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1e7f0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1e800 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1e810 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1e820 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1e830 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1e840 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e850 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1e860 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1e870 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1e880 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1e890 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1e8a0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1e8b0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1e8c0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1e8d0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1e8e0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1e8f0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1e900 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1e910 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
1e920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1e930 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
1e940 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1e950 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1e960 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1e970 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1e980 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1e990 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1e9a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e9b0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
1e9c0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
1e9d0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1e9e0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
1e9f0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1ea00 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1ea10 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1ea20 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1ea30 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
1ea40 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
1ea50 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1ea60 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1ea70 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1ea80 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
1ea90 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1eaa0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1eab0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
1eac0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ead0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
1eae0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
1eaf0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
1eb00 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
1eb10 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1eb20 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
1eb30 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
1eb40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eb50 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1eb60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1eb70 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1eb80 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1eb90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1eba0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1ebb0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1ebc0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1ebd0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1ebe0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1ebf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1ec00 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1ec10 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1ec20 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1ec30 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1ec40 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1ec50 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1ec60 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1ec70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1ec80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1ec90 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
1eca0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1ecb0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
1ecc0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
1ecd0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
1ece0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1ecf0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
1ed00 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1ed10 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
1ed20 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1ed30 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1ed40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1ed50 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1ed60 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1ed70 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1ed80 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1ed90 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1eda0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1edb0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
1edc0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
1edd0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1ede0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1edf0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1ee00 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1ee10 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1ee20 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1ee30 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1ee40 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1ee50 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1ee60 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1ee70 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1ee80 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1ee90 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1eea0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1eeb0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1eec0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
1eed0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1eee0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
1eef0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
1ef00 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
1ef10 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
1ef20 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
1ef30 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1ef40 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
1ef50 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
1ef60 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
1ef70 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
1ef80 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1ef90 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
1efa0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
1efb0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
1efc0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
1efd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
1efe0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
1eff0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
1f000 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
1f010 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
1f020 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
1f030 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
1f040 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1f050 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
1f060 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
1f070 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
1f080 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1f090 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
1f0a0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
1f0b0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
1f0c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1f0d0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
1f0e0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
1f0f0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
1f100 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
1f110 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
1f120 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
1f130 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1f140 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1f150 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1f160 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1f170 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1f180 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1f190 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1f1a0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1f1b0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1f1c0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1f1d0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1f1e0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
1f1f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1f200 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1f210 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1f220 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1f230 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1f240 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1f250 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1f260 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1f270 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1f280 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1f290 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1f2a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1f2b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1f2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1f2d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f2e0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1f2f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1f300 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1f310 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1f320 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1f330 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1f340 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1f350 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1f360 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1f370 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1f380 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1f390 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1f3a0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1f3b0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1f3c0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1f3d0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1f3e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1f3f0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1f400 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1f410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f420 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1f430 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1f440 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1f450 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1f460 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1f470 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1f480 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1f490 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1f4a0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1f4b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1f4c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1f4d0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1f4e0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1f4f0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1f500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f510 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1f520 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1f530 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1f540 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1f550 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1f560 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1f570 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f580 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1f590 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1f5a0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1f5b0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1f5c0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1f5d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f5e0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1f5f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1f600 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1f610 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1f620 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1f630 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
1f640 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1f650 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1f660 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1f670 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1f680 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1f690 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1f6a0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1f6b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1f6c0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1f6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1f6e0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1f6f0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1f700 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1f710 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1f720 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1f730 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1f740 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1f750 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1f760 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1f770 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1f780 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1f790 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1f7a0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1f7b0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1f7c0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1f7d0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1f7e0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1f7f0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1f800 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
1f810 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
1f820 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
1f830 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
1f840 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
1f850 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
1f860 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1f870 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
1f880 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
1f890 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
1f8a0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
1f8b0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
1f8c0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1f8d0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1f8e0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
1f8f0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
1f900 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1f910 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1f920 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1f930 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1f940 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1f950 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
1f960 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
1f970 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1f980 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
1f990 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
1f9a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
1f9b0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
1f9c0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
1f9d0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
1f9e0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
1f9f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
1fa00 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
1fa10 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
1fa20 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
1fa30 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
1fa40 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
1fa50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
1fa60 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
1fa70 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1fa80 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1fa90 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1faa0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1fab0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1fac0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1fad0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1fae0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1faf0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1fb00 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1fb10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1fb20 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1fb30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1fb40 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1fb50 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1fb60 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1fb70 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1fb80 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1fb90 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1fba0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1fbb0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1fbc0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1fbd0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1fbe0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1fbf0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1fc00 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1fc10 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1fc20 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1fc30 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1fc40 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1fc50 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1fc60 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1fc70 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1fc80 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1fc90 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1fca0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1fcb0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1fcc0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1fcd0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fce0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1fcf0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1fd00 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1fd10 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1fd20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1fd30 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1fd40 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1fd50 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1fd60 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1fd70 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1fd80 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1fd90 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1fda0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1fdb0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1fdc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1fdd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1fde0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1fdf0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1fe00 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1fe10 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1fe20 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
1fe30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1fe40 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
1fe50 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1fe60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1fe70 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1fe80 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1fe90 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1fea0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1feb0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1fec0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1fed0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1fee0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1fef0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1ff00 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1ff10 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1ff20 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1ff30 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1ff40 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1ff50 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1ff60 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1ff70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
1ff80 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
1ff90 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1ffa0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1ffb0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1ffc0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1ffd0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1ffe0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
1fff0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20000 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20010 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20020 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20030 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20040 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
20050 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
20060 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
20070 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20080 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
20090 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
200a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
200b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
200c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
200d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
200e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
200f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20100 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
20110 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
20120 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
20130 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
20140 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
20150 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
20160 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
20170 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20180 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20190 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
201a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
201b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
201c0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
201d0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
201e0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
201f0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
20200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20210 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
20220 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
20230 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
20240 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
20250 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
20260 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
20270 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
20280 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
20290 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
202a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
202b0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
202c0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
202d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
202e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
202f0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
20300 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
20310 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
20320 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
20330 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20340 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
20350 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
20360 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
20370 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
20380 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
20390 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
203a0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
203b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
203c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
203d0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
203e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
203f0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
20400 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20410 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
20420 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
20430 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
20440 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
20450 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
20460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
20470 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
20480 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20490 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
204a0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
204b0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
204c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
204d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
204e0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
204f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
20500 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
20510 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20520 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
20530 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
20540 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
20550 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
20560 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
20570 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
20590 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
205a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
205b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
205c0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
205d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
205e0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
205f0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
20600 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
20610 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20620 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
20630 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
20640 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
20650 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
20660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20670 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
20680 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
20690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
206a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
206b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
206c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
206d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
206e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
206f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20700 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
20710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20720 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
20730 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
20740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20750 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
20760 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
20770 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20780 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
20790 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
207a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
207b0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
207c0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
207d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
207e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
207f0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
20800 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20810 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
20820 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
20830 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20840 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
20850 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
20860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20870 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20880 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
20890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
208a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
208b0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
208c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
208d0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
208e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
208f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
20900 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
20910 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
20920 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
20930 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
20940 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
20950 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
20960 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
20970 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
20980 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
20990 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
209a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
209b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
209c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
209d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
209e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
209f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
20a00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
20a10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
20a20 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
20a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20a40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
20a50 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
20a60 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
20a70 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
20a80 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
20a90 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
20aa0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
20ab0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
20ac0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
20ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
20ae0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
20af0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
20b00 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
20b10 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
20b20 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
20b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20b40 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
20b50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
20b60 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
20b70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
20b80 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
20b90 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
20ba0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
20bb0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
20bc0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
20bd0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
20be0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
20bf0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
20c00 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
20c10 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
20c20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
20c30 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
20c40 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
20c50 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
20c60 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
20c70 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
20c80 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
20c90 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
20ca0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
20cb0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
20cc0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
20cd0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
20ce0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
20cf0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
20d00 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
20d10 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
20d20 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
20d30 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
20d40 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
20d50 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
20d60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
20d70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
20d80 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
20d90 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
20da0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
20db0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
20dc0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
20dd0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
20de0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
20df0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
20e00 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
20e10 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
20e20 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
20e30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
20e40 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
20e50 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
20e60 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
20e70 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
20e80 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
20e90 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
20ea0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
20eb0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
20ec0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
20ed0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
20ee0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
20ef0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
20f00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
20f10 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
20f20 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
20f30 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
20f40 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
20f50 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
20f60 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
20f70 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
20f80 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
20f90 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
20fa0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
20fb0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
20fc0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
20fd0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
20fe0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
20ff0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
21000 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
21010 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
21020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
21030 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
21040 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
21050 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
21060 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
21070 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
21080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21090 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
210a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
210b0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
210c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
210d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
210e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
210f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21110 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
21120 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
21130 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
21140 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
21150 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
21160 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
21170 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
21180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
21190 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
211a0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
211b0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
211c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
211d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
211e0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
211f0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
21200 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
21210 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
21220 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
21230 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
21240 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
21250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21260 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
21270 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
21280 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
21290 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
212a0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
212b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
212c0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
212d0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
212e0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
212f0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
21300 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
21310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21320 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
21330 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
21340 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
21350 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
21360 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
21370 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
21380 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
21390 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
213a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
213b0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
213c0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
213d0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
213e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
213f0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
21400 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
21410 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
21420 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
21430 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
21440 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
21450 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
21460 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
21470 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
21480 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
21490 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
214a0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
214b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
214c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
214d0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
214e0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
214f0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
21500 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
21510 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
21520 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
21530 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
21540 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
21550 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
21560 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
21570 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
21580 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
21590 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
215a0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
215b0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
215c0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
215d0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
215e0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
215f0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
21600 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
21610 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
21620 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
21630 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
21640 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
21650 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
21660 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
21670 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
21680 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
21690 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
216a0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
216b0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
216c0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
216d0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
216e0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
216f0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
21700 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
21710 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
21720 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
21730 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
21740 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
21750 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
21760 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
21770 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
21780 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
21790 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
217a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
217b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
217c0 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT2] compile-t
217d0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
217e0 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
217f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
21800 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21810 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
21820 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
21830 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
21840 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21850 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
21860 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
21870 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
21880 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
21890 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
218a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
218b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
218c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
218d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
218e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
218f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
21900 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
21910 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
21920 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
21930 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
21940 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
21950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
21960 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
21970 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
21980 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
21990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
219a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
219b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
219c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
219d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
219e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
219f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
21a00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
21a10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
21a20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
21a30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
21a40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
21a50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
21a60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
21a70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
21a80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
21a90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21aa0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
21ab0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
21ac0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
21ad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
21ae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
21af0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
21b00 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
21b10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
21b20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
21b30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
21b40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
21b50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
21b60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
21b70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
21b80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21b90 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
21ba0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
21bb0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
21bc0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
21bd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
21be0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
21bf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
21c00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
21c10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
21c20 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
21c30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
21c40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
21c50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
21c60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
21c70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
21c80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
21c90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
21ca0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
21cb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
21cc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
21cd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
21ce0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
21cf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
21d00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
21d10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
21d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
21d30 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
21d40 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
21d50 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
21d60 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
21d70 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
21d80 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
21d90 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
21da0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
21db0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21dc0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
21dd0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
21de0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
21df0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
21e00 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
21e10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21e20 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
21e30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
21e40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
21e50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
21e60 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
21e70 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
21e80 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
21e90 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
21ea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
21eb0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
21ec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21ed0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
21ee0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
21ef0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
21f00 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
21f10 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
21f20 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
21f30 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
21f40 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
21f50 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
21f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
21f70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
21f80 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
21f90 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
21fa0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
21fb0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
21fc0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
21fd0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
21fe0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
21ff0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
22000 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
22010 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
22020 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
22030 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
22040 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
22050 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
22060 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
22070 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
22080 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
22090 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
220a0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
220b0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
220c0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
220d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
220e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
220f0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
22100 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
22110 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
22120 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22130 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
22140 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
22150 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
22160 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
22170 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
22180 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
22190 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
221a0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
221b0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
221c0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
221d0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
221e0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
221f0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
22200 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
22210 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
22220 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
22230 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
22240 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
22250 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
22260 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
22270 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
22280 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
22290 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
222a0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
222b0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
222c0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
222d0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
222e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
222f0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
22300 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
22310 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
22320 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
22330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
22340 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
22350 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
22360 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
22370 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
22380 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
22390 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
223a0 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
223b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
223c0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
223d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
223e0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
223f0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
22400 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
22410 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
22420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
22430 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22440 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
22450 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
22460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22470 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
22480 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
22490 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
224a0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
224b0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
224c0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
224d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
224e0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
224f0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
22500 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
22510 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
22520 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
22530 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
22540 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
22550 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
22560 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
22570 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
22580 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
22590 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
225a0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
225b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
225c0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
225d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
225e0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
225f0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
22600 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
22610 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
22620 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22630 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
22640 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
22650 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
22660 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
22670 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
22680 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
22690 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
226a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
226b0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
226c0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
226d0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
226e0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
226f0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
22700 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
22710 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
22720 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
22730 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
22740 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
22750 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
22760 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
22770 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
22780 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
22790 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
227a0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
227b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
227c0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
227d0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
227e0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
227f0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
22800 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
22810 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
22820 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
22830 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
22840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
22850 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
22860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
22870 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
22880 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
22890 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
228a0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
228b0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
228c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
228d0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
228e0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
228f0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
22900 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
22910 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
22920 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
22930 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
22940 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
22950 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
22960 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
22970 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
22980 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
22990 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
229a0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
229b0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
229c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
229d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
229e0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
229f0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
22a00 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
22a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
22a20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
22a30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
22a40 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
22a50 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
22a60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
22a70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
22a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
22a90 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
22aa0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
22ab0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22ac0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
22ad0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
22ae0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
22af0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
22b00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
22b10 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
22b20 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
22b30 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
22b40 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
22b50 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
22b60 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
22b70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22b80 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
22b90 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
22ba0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
22bb0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
22bc0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
22bd0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
22be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
22bf0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
22c00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
22c10 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
22c20 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
22c30 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
22c40 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
22c50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
22c60 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
22c70 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
22c80 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
22c90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
22ca0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
22cb0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
22cc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
22cd0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
22ce0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
22cf0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
22d00 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
22d10 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
22d20 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
22d30 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
22d40 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
22d50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
22d60 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
22d70 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
22d80 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
22d90 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
22da0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
22db0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
22dc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
22dd0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
22de0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
22df0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
22e00 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
22e10 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
22e20 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
22e30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
22e40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
22e50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
22e60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
22e70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
22e80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
22e90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
22ea0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
22eb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
22ec0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
22ed0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
22ee0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
22ef0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
22f00 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
22f10 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
22f20 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
22f30 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
22f40 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
22f50 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
22f60 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
22f70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
22f80 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
22f90 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
22fa0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
22fb0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
22fc0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
22fd0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
22fe0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
22ff0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
23000 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
23010 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
23020 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
23030 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
23040 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
23050 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
23060 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
23070 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
23080 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
23090 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
230a0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
230b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
230c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
230d0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
230e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
230f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
23100 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
23110 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
23120 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
23130 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
23140 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
23150 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
23160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23170 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
23180 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
23190 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
231a0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
231b0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
231c0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
231d0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
231e0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
231f0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
23200 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
23210 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
23220 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
23230 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
23240 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
23250 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
23260 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
23270 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
23280 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
23290 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
232a0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
232b0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
232c0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
232d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
232e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
232f0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
23300 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
23310 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
23320 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
23330 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
23340 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
23350 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
23360 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
23370 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
23380 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
23390 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
233a0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
233b0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
233c0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
233d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
233e0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
233f0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
23400 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
23410 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
23420 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
23430 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
23440 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
23450 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
23460 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
23470 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
23480 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
23490 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
234a0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
234b0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
234c0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
234d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
234e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
234f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
23500 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
23510 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
23520 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
23530 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
23540 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
23550 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
23560 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23570 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
23580 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23590 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
235a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
235b0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
235c0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
235d0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
235e0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
235f0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
23600 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
23610 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
23620 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
23630 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
23640 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
23650 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
23660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
23670 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
23680 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
23690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
236a0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
236b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
236c0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
236d0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
236e0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
236f0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
23700 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
23710 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
23720 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
23730 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
23740 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
23750 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
23760 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
23770 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
23780 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
23790 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
237a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
237b0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
237c0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
237d0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
237e0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
237f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
23800 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
23810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
23820 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
23830 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
23840 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
23850 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
23860 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
23870 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
23880 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
23890 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
238a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
238b0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
238c0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
238d0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
238e0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
238f0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
23900 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
23910 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
23920 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
23930 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
23940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
23950 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
23960 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
23970 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
23980 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
23990 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
239a0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
239b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
239c0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
239d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
239e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
239f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
23a00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
23a10 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
23a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
23a30 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
23a40 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
23a50 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
23a60 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
23a70 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
23a80 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
23a90 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
23aa0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
23ab0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
23ac0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
23ad0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
23ae0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
23af0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
23b00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
23b10 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
23b20 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
23b30 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
23b40 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
23b50 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
23b60 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
23b70 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
23b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23b90 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
23ba0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
23bb0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
23bc0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
23bd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
23be0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
23bf0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
23c00 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
23c10 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
23c20 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
23c30 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
23c40 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
23c50 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
23c60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
23c70 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
23c80 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
23c90 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
23ca0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
23cb0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
23cc0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
23cd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
23ce0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
23cf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23d00 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
23d10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23d20 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
23d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
23d40 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
23d50 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
23d60 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
23d70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
23d80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
23d90 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
23da0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
23db0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
23dc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
23dd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
23de0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
23df0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
23e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
23e10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
23e20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
23e30 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
23e40 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
23e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23e60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
23e70 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
23e80 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
23e90 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
23ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
23eb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
23ec0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
23ed0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
23ee0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
23ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
23f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23f10 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
23f20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
23f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
23f40 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
23f50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
23f60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23f70 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
23f80 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
23f90 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
23fa0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
23fb0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
23fc0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
23fd0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
23fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23ff0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
24000 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
24010 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
24020 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
24030 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
24040 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
24050 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
24060 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
24070 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
24080 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
24090 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
240a0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
240b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
240c0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
240d0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
240e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
240f0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
24100 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
24110 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
24120 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
24130 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
24140 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
24150 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
24160 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
24170 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
24180 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
24190 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
241a0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
241b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
241c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
241d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
241e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
241f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24200 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
24210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
24220 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
24230 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
24240 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24250 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
24260 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
24270 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
24280 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
24290 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
242a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
242b0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
242c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
242d0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
242e0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
242f0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
24300 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24310 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
24320 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
24330 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
24340 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
24350 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
24360 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
24370 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
24380 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
24390 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
243a0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
243b0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
243c0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
243d0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
243e0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
243f0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
24400 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
24410 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
24420 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
24430 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
24440 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
24450 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
24460 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
24470 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
24480 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
24490 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
244a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
244b0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
244c0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
244d0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
244e0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
244f0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
24500 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
24510 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
24520 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
24530 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
24540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
24550 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
24560 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
24570 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
24580 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
24590 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
245a0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
245b0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
245c0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
245d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
245e0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
245f0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24600 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
24610 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
24620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
24630 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
24640 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
24650 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24660 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
24670 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24680 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24690 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
246a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
246b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
246c0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
246d0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
246e0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
246f0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
24700 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
24710 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
24720 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
24730 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
24740 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
24750 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
24760 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
24770 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24780 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
24790 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
247a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
247b0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
247c0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
247d0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
247e0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
247f0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
24800 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
24810 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
24820 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
24830 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
24840 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
24850 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
24860 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
24870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24880 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
24890 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
248a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
248b0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
248c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
248d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
248e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
248f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
24900 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
24910 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
24920 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
24930 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
24940 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
24950 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24960 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
24970 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
24980 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
24990 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
249a0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
249b0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
249c0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
249d0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
249e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
249f0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
24a00 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
24a10 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
24a20 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
24a30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
24a40 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
24a50 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
24a60 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
24a70 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
24a80 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
24a90 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
24aa0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
24ab0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
24ac0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
24ad0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24ae0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
24af0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
24b00 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
24b10 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
24b20 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
24b30 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
24b40 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
24b50 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
24b60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
24b70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
24b80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
24b90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
24ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24bc0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
24bd0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
24be0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
24bf0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
24c00 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
24c10 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
24c20 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
24c30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
24c40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
24c50 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
24c60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
24c70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
24c80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24c90 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
24ca0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
24cb0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
24cc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
24cd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
24ce0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
24cf0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
24d00 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
24d10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
24d20 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
24d30 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
24d40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
24d50 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
24d60 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
24d70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
24d80 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
24d90 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
24da0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
24db0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
24dc0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
24dd0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
24de0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
24df0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24e00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
24e10 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
24e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24e30 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
24e40 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
24e50 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
24e60 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
24e70 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
24e80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
24e90 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
24ea0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
24eb0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
24ec0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
24ed0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
24ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
24ef0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
24f00 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
24f10 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
24f20 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
24f30 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
24f40 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
24f50 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
24f60 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
24f70 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
24f80 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
24f90 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
24fa0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
24fb0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
24fc0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
24fd0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
24fe0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
24ff0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
25000 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
25010 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
25020 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
25030 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
25040 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
25050 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
25060 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
25070 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
25080 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
25090 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
250a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
250b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
250c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
250d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
250e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
250f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
25100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25110 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
25120 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
25130 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
25140 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
25150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
25160 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
25170 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
25180 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
25190 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
251a0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
251b0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
251c0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
251d0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
251e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
251f0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
25200 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
25210 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
25220 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
25230 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
25240 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
25250 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
25260 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
25270 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
25280 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
25290 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
252a0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
252b0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
252c0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
252d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
252e0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
252f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25300 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
25310 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
25320 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
25330 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
25340 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
25350 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
25360 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
25370 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
25380 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
25390 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
253a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
253b0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
253c0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
253d0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
253e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
253f0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
25400 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
25410 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
25420 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
25430 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
25440 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
25450 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
25460 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
25470 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
25480 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
25490 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
254a0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
254b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
254c0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
254d0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
254e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
254f0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
25500 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
25510 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
25520 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
25530 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
25540 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
25550 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
25560 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
25570 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
25580 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
25590 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
255a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
255b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
255c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
255d0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
255e0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
255f0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
25600 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25610 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
25620 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
25630 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
25640 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
25650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
25660 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
25670 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
25680 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
25690 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
256a0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
256b0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
256c0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
256d0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
256e0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
256f0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
25700 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
25710 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
25720 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
25730 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
25740 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
25750 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
25760 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
25770 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
25780 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
25790 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
257a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
257b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
257c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
257d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
257e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
257f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
25800 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
25810 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
25820 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
25830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
25840 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
25850 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
25860 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
25870 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
25880 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
25890 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
258a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
258b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
258c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
258d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
258e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
258f0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
25900 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
25910 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
25920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25930 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
25940 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
25950 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
25960 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
25970 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
25980 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25990 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
259a0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
259b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
259c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
259d0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
259e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
259f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25a00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25a10 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
25a20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25a30 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
25a40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25a50 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
25a60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25a70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
25a90 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
25aa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25ab0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25ac0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
25ad0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
25ae0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
25af0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
25b00 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
25b10 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
25b20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
25b30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
25b40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25b50 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
25b60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
25b70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
25b80 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
25b90 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
25ba0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
25bb0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
25bc0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
25bd0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
25be0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
25bf0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
25c00 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
25c10 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
25c20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
25c30 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
25c40 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
25c50 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
25c60 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
25c70 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
25c80 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
25c90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25ca0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
25cb0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
25cc0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
25cd0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
25ce0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
25cf0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
25d00 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
25d10 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
25d20 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
25d30 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
25d40 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
25d50 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
25d60 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
25d70 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
25d80 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
25d90 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
25da0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
25db0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
25dc0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
25dd0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
25de0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
25df0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
25e00 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
25e10 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
25e20 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
25e30 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
25e40 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
25e50 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
25e60 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
25e70 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
25e80 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
25e90 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
25ea0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
25eb0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
25ec0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
25ed0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
25ee0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
25ef0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
25f00 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
25f10 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
25f20 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
25f30 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
25f40 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
25f50 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
25f60 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
25f70 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
25f80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25f90 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
25fa0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25fb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25fd0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
25fe0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
25ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
26000 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
26010 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
26020 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
26030 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
26040 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
26050 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
26060 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26070 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26080 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
26090 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
260a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
260b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
260c0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
260d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
260e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
260f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
26100 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
26110 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
26120 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
26130 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
26140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
26150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
26160 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
26170 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
26180 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
26190 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
261a0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
261b0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
261c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
261d0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
261e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
261f0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
26200 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
26210 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
26220 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
26230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26240 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
26250 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
26260 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
26270 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
26280 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
26290 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
262a0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
262b0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
262c0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
262d0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
262e0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
262f0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
26300 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
26310 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
26320 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
26330 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
26340 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
26350 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
26360 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
26370 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
26380 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
26390 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
263a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
263b0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
263c0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
263d0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
263e0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
263f0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
26400 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
26410 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
26420 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
26430 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
26440 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
26450 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
26460 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
26470 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
26480 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
26490 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
264a0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
264b0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
264c0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
264d0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
264e0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
264f0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
26500 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
26510 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
26520 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
26530 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
26540 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
26550 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
26560 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
26570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
26580 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
26590 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
265a0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
265b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
265c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
265d0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
265e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
265f0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
26600 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
26610 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
26620 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
26630 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
26640 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
26650 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
26660 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
26670 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
26680 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
26690 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
266a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
266b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
266c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
266d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
266e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
266f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
26700 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
26710 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
26720 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
26730 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
26740 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
26750 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
26760 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
26770 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
26780 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
26790 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
267a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
267b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
267c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
267d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
267e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
267f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
26800 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
26810 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
26820 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
26830 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
26840 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
26850 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
26860 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
26870 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
26880 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
26890 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
268a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
268b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
268c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
268d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
268e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
268f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
26900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26910 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
26920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26930 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
26940 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
26950 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
26960 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
26970 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
26980 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
26990 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
269a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
269b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
269c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
269d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
269e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
269f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
26a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26a10 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
26a20 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
26a30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
26a40 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
26a50 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
26a60 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
26a70 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
26a80 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
26a90 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
26aa0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
26ab0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
26ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26ad0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
26ae0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
26af0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
26b00 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
26b10 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
26b20 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
26b30 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
26b40 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
26b50 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
26b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
26b70 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
26b80 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
26b90 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
26ba0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
26bb0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
26bc0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
26bd0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
26be0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
26bf0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
26c00 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
26c10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26c20 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
26c30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26c40 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
26c50 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
26c60 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
26c70 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
26c80 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
26c90 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
26ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
26cb0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
26cc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26cd0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
26ce0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
26cf0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
26d00 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
26d10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
26d20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
26d30 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
26d40 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
26d50 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
26d60 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
26d70 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
26d80 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
26d90 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
26da0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
26db0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
26dc0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
26dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
26de0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
26df0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
26e00 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
26e10 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
26e20 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
26e30 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
26e40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
26e50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
26e60 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
26e70 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
26e80 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
26e90 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
26ea0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
26eb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
26ec0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
26ed0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
26ee0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
26ef0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26f00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
26f10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
26f20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
26f30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
26f40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
26f50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
26f60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
26f70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
26f80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
26f90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
26fa0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
26fb0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
26fc0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26fd0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
26fe0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
26ff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
27000 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27020 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
27030 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27040 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
27050 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
27060 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
27070 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
27080 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
27090 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
270a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
270b0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
270c0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
270d0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
270e0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
270f0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
27100 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
27110 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
27120 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
27130 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
27140 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
27150 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
27160 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
27170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
27190 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
271a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
271b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
271c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
271d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
271e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
271f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
27200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27210 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
27220 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
27230 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
27240 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
27250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27260 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
27270 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
27280 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
27290 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
272a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
272b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
272c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
272d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
272e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
272f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
27300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27310 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27320 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
27330 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
27340 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
27350 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27360 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
27370 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
27380 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
27390 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
273a0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
273b0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
273c0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
273d0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
273e0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
273f0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
27400 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
27410 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
27420 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
27430 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
27440 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
27450 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
27460 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
27470 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
27480 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
27490 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
274a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
274b0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
274c0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
274d0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
274e0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
274f0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
27500 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
27510 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
27520 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
27530 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
27540 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
27550 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
27560 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
27570 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
27580 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
27590 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
275a0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
275b0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
275c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
275d0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
275e0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
275f0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
27600 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
27610 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
27620 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
27630 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
27640 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
27650 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
27660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
27670 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
27680 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
27690 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
276a0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
276b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
276c0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
276d0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
276e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
276f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
27700 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
27710 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
27720 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
27730 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
27740 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
27750 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
27760 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27770 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
27780 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
27790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
277a0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
277b0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
277c0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
277d0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
277e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
277f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
27800 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
27810 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
27820 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
27830 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
27840 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
27850 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
27860 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
27870 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
27880 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
27890 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
278a0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
278b0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
278c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
278d0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
278e0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
278f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27900 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
27910 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
27920 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
27930 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
27940 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
27950 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
27960 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
27970 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
27980 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
27990 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
279a0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
279b0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
279c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
279d0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
279e0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
279f0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
27a00 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
27a10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
27a20 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
27a30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
27a40 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
27a50 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
27a60 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
27a70 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
27a80 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
27a90 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
27aa0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27ab0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
27ac0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27ad0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
27ae0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
27af0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
27b00 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
27b10 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
27b20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
27b30 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
27b40 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
27b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27b60 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
27b70 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
27b80 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
27b90 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
27ba0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
27bb0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
27bc0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
27bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27be0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27bf0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
27c00 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
27c10 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
27c20 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
27c30 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
27c40 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
27c50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
27c60 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
27c70 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
27c80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
27c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
27ca0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
27cb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
27cc0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
27cd0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
27ce0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
27cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
27d00 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
27d10 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
27d20 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
27d30 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
27d40 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
27d50 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
27d60 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
27d70 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
27d80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27d90 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
27da0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
27db0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
27dc0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
27dd0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
27de0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
27df0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
27e00 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
27e10 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
27e20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
27e30 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
27e40 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
27e50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27e60 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
27e70 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
27e80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27e90 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
27ea0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
27eb0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
27ec0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
27ed0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
27ee0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
27ef0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
27f00 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
27f10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
27f20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
27f30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
27f40 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
27f50 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
27f60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
27f70 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
27f80 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
27f90 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
27fa0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
27fb0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
27fc0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
27fd0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
27fe0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
27ff0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
28000 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
28010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
28020 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
28030 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
28040 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
28050 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
28060 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
28070 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
28080 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
28090 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
280a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
280b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
280c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
280d0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
280e0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
280f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28100 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
28110 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
28120 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
28130 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
28140 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
28150 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
28160 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
28170 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
28180 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
28190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
281a0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
281b0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
281c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
281d0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
281e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
281f0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
28200 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
28210 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
28220 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
28230 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
28240 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
28250 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
28260 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
28270 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28280 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
28290 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
282a0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
282b0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
282c0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
282d0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
282e0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
282f0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
28300 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
28310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28320 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
28330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28340 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
28350 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
28360 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
28370 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28380 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
28390 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
283a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
283b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
283c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
283d0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
283e0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
283f0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
28400 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
28410 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
28420 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
28430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
28440 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
28450 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
28460 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
28470 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
28480 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
28490 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
284a0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
284b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
284c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
284d0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
284e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
284f0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
28500 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
28510 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
28520 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28530 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
28540 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
28550 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28560 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
28570 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
28580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28590 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
285a0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
285b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
285c0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
285d0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
285e0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
285f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
28600 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
28610 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
28620 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
28630 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
28640 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
28650 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
28660 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
28670 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
28680 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
28690 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
286a0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
286b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
286c0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
286d0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
286e0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
286f0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
28700 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
28710 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
28720 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
28730 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
28740 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
28750 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
28760 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
28770 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
28780 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
28790 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
287a0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
287b0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
287c0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
287d0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
287e0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
287f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
28800 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
28810 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28820 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
28830 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
28840 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
28850 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
28860 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
28870 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
28880 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
28890 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
288a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
288b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
288c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
288d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
288e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
288f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
28900 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
28910 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
28920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
28930 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
28940 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
28950 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
28960 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
28970 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
28980 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28990 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
289a0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
289b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
289c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
289d0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
289e0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
289f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
28a00 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
28a10 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
28a20 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
28a30 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
28a40 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
28a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
28a60 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
28a70 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
28a80 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
28a90 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
28aa0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
28ab0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28ac0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
28ad0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
28ae0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
28af0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28b00 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
28b10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
28b20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28b30 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
28b40 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
28b50 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
28b60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
28b70 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
28b80 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
28b90 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
28ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
28bb0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
28bc0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
28bd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
28be0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
28bf0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
28c00 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
28c10 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
28c20 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
28c30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
28c40 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
28c50 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
28c60 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
28c70 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
28c80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
28c90 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
28ca0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
28cb0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
28cc0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
28cd0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
28ce0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
28cf0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
28d00 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
28d10 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
28d20 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
28d30 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
28d40 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
28d50 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
28d60 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
28d70 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
28d80 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
28d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28da0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
28db0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
28dc0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
28dd0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
28de0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
28df0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
28e00 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
28e10 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
28e20 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
28e30 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
28e40 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
28e50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
28e60 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
28e70 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
28e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28e90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
28ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28eb0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
28ec0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
28ed0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
28ee0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
28ef0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
28f00 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
28f10 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
28f20 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
28f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28f40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
28f50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
28f60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28f70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
28f80 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
28f90 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
28fa0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
28fb0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
28fc0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
28fd0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
28fe0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
28ff0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
29000 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
29010 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
29020 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
29030 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
29040 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
29050 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
29060 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
29070 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
29080 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
29090 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
290a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
290b0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
290c0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
290d0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
290e0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
290f0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
29100 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
29110 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
29120 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
29130 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
29140 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
29150 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
29160 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
29170 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
29180 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
29190 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
291a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
291b0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
291c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
291d0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
291e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
291f0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
29200 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
29210 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
29220 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
29230 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
29240 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
29250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
29260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29270 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
29280 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
29290 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
292a0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
292b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
292c0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
292d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
292e0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
292f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29300 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
29310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29320 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
29330 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
29340 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
29350 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
29360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29370 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
29380 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
29390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
293a0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
293b0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
293c0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
293d0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
293e0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
293f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29400 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
29410 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29420 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
29430 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
29440 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
29450 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
29460 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
29470 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
29480 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
29490 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
294a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
294b0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
294c0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
294d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
294e0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
294f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
29500 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
29510 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
29520 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
29530 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
29540 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
29550 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
29560 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
29570 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
29580 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
29590 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
295a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
295b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
295c0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
295d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
295e0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
295f0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
29600 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
29610 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
29620 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
29630 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
29640 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
29650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29660 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
29670 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
29680 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
29690 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
296a0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
296b0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
296c0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
296d0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
296e0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
296f0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
29700 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
29710 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
29720 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
29730 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
29740 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
29750 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
29760 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
29770 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
29780 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
29790 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
297a0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
297b0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
297c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
297d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
297e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
297f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
29800 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
29810 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29830 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
29840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29850 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
29860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
29870 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
29880 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29890 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
298a0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
298b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
298c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
298d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
298e0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
298f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
29900 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
29910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29920 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
29930 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
29940 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29960 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29970 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
29980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29990 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
299a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
299b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
299c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
299d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
299e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
299f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
29a00 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
29a10 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
29a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29a30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
29a40 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
29a50 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
29a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a70 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
29a80 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
29a90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
29aa0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
29ab0 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a  ed no errors or.
29ac0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
29ad0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
29ae0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
29af0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
29b00 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
29b10 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
29b20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
29b30 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
29b40 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
29b50 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
29b60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
29b70 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
29b80 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
29b90 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
29ba0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
29bb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
29bc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
29bd0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
29be0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
29bf0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
29c00 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
29c10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29c20 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
29c30 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
29c40 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
29c50 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
29c60 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
29c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29c80 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
29c90 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
29ca0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
29cb0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
29cc0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
29cd0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
29ce0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
29cf0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
29d00 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
29d10 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
29d20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
29d30 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
29d40 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
29d50 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
29d60 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
29d70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
29d80 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
29d90 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
29da0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
29db0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
29dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
29dd0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
29de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29df0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
29e00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
29e10 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
29e20 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
29e30 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
29e40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
29e50 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
29e60 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
29e70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
29e80 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
29e90 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
29ea0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
29eb0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
29ec0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
29ed0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
29ee0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
29ef0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
29f00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
29f10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
29f20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
29f30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
29f40 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
29f50 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
29f60 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
29f70 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
29f80 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
29f90 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
29fa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
29fb0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
29fc0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
29fd0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
29fe0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29ff0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2a000 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2a010 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2a020 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2a030 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2a040 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2a050 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2a060 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2a070 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2a080 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2a090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a0a0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2a0b0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2a0c0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2a0d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2a0e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2a0f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2a100 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2a110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a120 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2a130 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2a140 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2a150 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2a160 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2a170 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2a180 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2a190 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2a1a0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2a1b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2a1c0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2a1d0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2a1e0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2a1f0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2a200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a210 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2a220 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2a230 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2a240 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2a250 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2a260 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2a270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a280 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2a290 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2a2a0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2a2b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a2c0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2a2d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a2e0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2a2f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2a300 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a310 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a320 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2a330 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2a340 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2a350 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2a360 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2a370 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2a380 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2a390 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a3a0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2a3b0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2a3c0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a3d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2a3e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2a3f0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2a400 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2a410 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2a420 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2a430 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2a440 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2a450 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2a460 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2a470 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2a480 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2a490 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2a4a0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2a4b0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2a4c0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2a4d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2a4e0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2a4f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2a500 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2a510 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2a520 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2a530 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2a540 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2a550 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2a560 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2a570 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2a580 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2a590 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2a5a0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2a5b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a5c0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2a5d0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2a5e0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2a5f0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2a600 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2a610 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2a620 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2a630 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a640 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2a650 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2a660 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2a670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a680 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2a690 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2a6a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2a6b0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2a6c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2a6d0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2a6e0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2a6f0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2a700 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2a710 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2a720 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2a730 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2a740 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2a750 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2a760 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2a770 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2a780 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2a790 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2a7a0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2a7b0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2a7c0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2a7d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2a7e0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2a7f0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2a800 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2a810 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2a820 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2a830 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2a840 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2a850 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2a860 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2a870 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2a880 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2a890 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2a8a0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2a8b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2a8c0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2a8d0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2a8e0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2a8f0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2a900 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2a910 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2a920 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2a930 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2a940 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2a950 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2a960 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2a970 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2a980 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2a990 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2a9a0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2a9b0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2a9c0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2a9d0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2a9e0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2a9f0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2aa00 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2aa10 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2aa20 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2aa30 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2aa40 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2aa50 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2aa60 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2aa70 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2aa80 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2aa90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2aaa0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2aab0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2aac0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2aad0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2aae0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2aaf0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2ab00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2ab10 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ab20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2ab30 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2ab40 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2ab50 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2ab60 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2ab70 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2ab80 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2ab90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2aba0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2abb0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2abc0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2abd0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2abe0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2abf0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2ac00 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2ac10 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2ac20 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2ac30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2ac40 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2ac50 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2ac60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2ac70 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2ac80 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2ac90 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2aca0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2acb0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2acc0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2acd0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2ace0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2acf0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2ad00 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2ad10 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2ad20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2ad30 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2ad40 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2ad50 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2ad60 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2ad70 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2ad80 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2ad90 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2ada0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2adb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2adc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2add0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2ade0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2adf0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2ae00 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2ae10 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2ae20 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2ae30 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2ae40 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2ae50 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2ae60 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2ae70 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2ae80 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2ae90 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2aea0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2aeb0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2aec0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2aed0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2aee0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2aef0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2af00 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2af10 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2af20 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2af30 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2af40 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2af50 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2af60 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2af70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2af80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2af90 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2afa0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2afb0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2afc0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2afd0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2afe0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2aff0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2b000 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2b010 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2b020 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2b030 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2b040 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2b050 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2b060 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2b070 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2b080 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2b090 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2b0a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b0b0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2b0c0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2b0d0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2b0e0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2b0f0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2b100 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2b110 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2b120 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2b130 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2b140 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2b150 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2b160 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2b170 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2b180 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b190 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2b1a0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2b1b0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2b1c0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2b1d0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2b1e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2b1f0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2b200 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2b210 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2b220 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2b230 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2b240 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2b250 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2b260 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2b270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b280 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2b290 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2b2a0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2b2b0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2b2c0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2b2d0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2b2e0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2b2f0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2b300 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2b310 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2b320 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2b330 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2b340 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2b350 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2b360 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2b370 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2b380 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2b390 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2b3a0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2b3b0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2b3c0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2b3d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2b3e0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2b3f0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2b400 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2b410 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2b420 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2b430 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2b440 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2b450 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2b460 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2b470 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2b480 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2b490 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2b4a0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2b4b0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2b4c0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2b4d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b4e0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2b4f0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2b500 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2b510 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2b520 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2b530 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2b540 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2b550 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2b560 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2b570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b580 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2b590 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2b5a0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2b5b0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2b5c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2b5d0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
2b5e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b5f0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2b600 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2b610 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2b620 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2b630 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2b640 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2b650 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2b660 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2b670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2b680 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2b690 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2b6a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2b6b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2b6c0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2b6d0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2b6e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b6f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2b700 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2b710 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2b720 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2b730 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2b740 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2b750 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2b760 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2b770 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2b780 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2b790 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2b7a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2b7b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2b7c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2b7d0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2b7e0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
2b7f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b800 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2b810 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2b820 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2b830 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2b840 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2b850 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2b860 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2b870 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2b880 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2b890 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2b8a0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2b8b0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2b8c0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2b8d0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2b8e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2b8f0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2b900 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2b910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2b920 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2b930 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2b940 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2b950 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2b960 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2b970 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2b980 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2b990 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2b9a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2b9b0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2b9c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2b9d0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2b9e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2b9f0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2ba00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2ba10 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2ba20 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2ba30 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2ba40 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2ba50 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2ba60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ba70 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2ba80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2ba90 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2baa0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2bab0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2bac0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2bad0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2bae0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2baf0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2bb00 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2bb10 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2bb20 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2bb30 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2bb40 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2bb50 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2bb60 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2bb70 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2bb80 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2bb90 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2bba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2bbb0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2bbc0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2bbd0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2bbe0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2bbf0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2bc00 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2bc10 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2bc20 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2bc30 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2bc40 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2bc50 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2bc60 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
2bc70 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2bc80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2bc90 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2bca0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2bcb0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2bcc0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2bcd0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2bce0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2bcf0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2bd00 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2bd10 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2bd20 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2bd30 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2bd40 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2bd50 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2bd60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2bd70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2bd80 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2bd90 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2bda0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2bdb0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2bdc0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2bdd0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2bde0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2bdf0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
2be00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2be10 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2be20 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2be30 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
2be40 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2be50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2be60 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2be70 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2be80 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2be90 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2bea0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2beb0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2bec0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2bed0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2bee0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2bef0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2bf00 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2bf10 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2bf20 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2bf30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2bf40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2bf50 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2bf60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2bf70 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2bf80 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2bf90 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2bfa0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2bfb0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
2bfc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2bfd0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2bfe0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2bff0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2c000 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c010 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2c020 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2c030 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c040 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2c050 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2c060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2c070 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2c080 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2c090 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2c0a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2c0b0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2c0c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2c0d0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2c0e0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2c0f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c100 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2c110 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2c120 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2c130 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c140 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2c150 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2c160 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2c170 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
2c180 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2c190 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2c1a0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2c1b0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2c1c0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2c1d0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2c1e0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2c1f0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2c200 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c210 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2c220 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2c230 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2c240 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2c250 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2c260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c270 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c280 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
2c290 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
2c2a0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2c2b0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2c2c0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2c2d0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
2c2e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2c2f0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
2c300 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c310 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
2c320 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
2c330 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
2c340 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
2c350 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
2c360 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
2c370 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
2c380 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2c390 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2c3a0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2c3b0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2c3c0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2c3d0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2c3e0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2c3f0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2c400 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2c410 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2c420 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2c430 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2c440 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2c450 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2c460 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2c470 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2c480 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
2c490 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2c4a0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2c4b0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2c4c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2c4d0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
2c4e0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
2c4f0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
2c500 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
2c510 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2c520 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2c530 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
2c540 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2c550 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2c560 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2c570 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2c580 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2c590 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2c5a0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2c5b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2c5c0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2c5d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2c5e0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2c5f0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2c600 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2c610 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c620 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2c630 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2c640 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2c650 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2c660 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2c670 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2c680 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c690 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2c6a0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2c6b0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2c6c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2c6d0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2c6e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2c6f0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
2c700 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c710 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2c720 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2c730 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2c740 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
2c750 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2c760 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2c770 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2c780 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2c790 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2c7a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2c7b0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2c7c0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
2c7d0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
2c7e0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2c7f0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2c800 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
2c810 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2c820 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c830 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2c840 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c850 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c860 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2c870 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2c880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c890 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2c8a0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2c8b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2c8c0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2c8d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2c8e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2c8f0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2c900 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2c910 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2c920 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2c930 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2c940 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2c950 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2c960 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2c970 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2c980 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2c990 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2c9a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2c9b0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2c9c0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2c9d0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2c9e0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2c9f0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2ca00 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2ca10 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2ca20 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2ca30 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2ca40 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2ca50 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2ca60 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2ca70 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2ca80 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2ca90 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2caa0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2cab0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2cac0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2cad0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2cae0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2caf0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2cb00 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2cb10 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2cb20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2cb30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2cb40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2cb50 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2cb60 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2cb70 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2cb80 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2cb90 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2cba0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2cbb0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
2cbc0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
2cbd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
2cbe0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
2cbf0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
2cc00 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
2cc10 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
2cc20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2cc30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
2cc40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
2cc50 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
2cc60 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
2cc70 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
2cc80 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
2cc90 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
2cca0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2ccb0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
2ccc0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
2ccd0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
2cce0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
2ccf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cd00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cd10 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2cd20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2cd30 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
2cd40 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
2cd50 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
2cd60 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2cd70 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
2cd80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
2cd90 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
2cda0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
2cdb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2cdc0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
2cdd0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2cde0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
2cdf0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
2ce00 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
2ce10 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
2ce20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
2ce30 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2ce40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ce50 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
2ce60 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2ce70 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2ce80 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
2ce90 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
2cea0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
2ceb0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2cec0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2ced0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
2cee0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
2cef0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2cf00 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
2cf10 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
2cf20 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2cf30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2cf40 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2cf50 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2cf60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2cf70 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2cf80 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2cf90 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2cfa0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2cfb0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
2cfc0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
2cfd0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2cfe0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2cff0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
2d000 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2d010 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2d020 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2d030 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2d040 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2d050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2d060 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2d070 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2d080 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2d090 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2d0a0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2d0b0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2d0c0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2d0d0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2d0e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2d0f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d100 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2d110 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2d120 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2d130 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2d140 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2d150 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2d160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d170 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2d180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d190 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2d1a0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2d1b0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2d1c0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2d1d0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2d1e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2d1f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2d200 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2d210 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2d220 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2d230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2d250 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2d260 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2d270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d280 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d290 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2d2a0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2d2b0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2d2c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2d2d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2d2e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d2f0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2d300 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d310 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d320 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2d330 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2d340 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2d350 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2d360 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2d370 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d380 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2d390 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2d3a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2d3b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d3c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
2d3d0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2d3e0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2d3f0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2d400 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2d410 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2d420 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2d430 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2d440 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2d450 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2d460 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2d470 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2d480 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2d490 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2d4a0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2d4b0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2d4c0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2d4d0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2d4e0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2d4f0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2d500 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2d510 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2d520 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2d530 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2d540 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2d550 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2d560 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2d570 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2d580 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2d590 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2d5a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2d5b0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2d5c0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2d5d0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2d5e0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2d5f0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2d600 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2d610 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2d620 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2d630 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2d640 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2d650 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2d660 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2d670 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2d680 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2d690 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2d6a0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2d6b0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2d6c0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2d6d0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2d6e0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2d6f0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2d700 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
2d710 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2d720 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2d730 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
2d740 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
2d750 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2d760 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2d770 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2d780 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2d790 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2d7a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2d7b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
2d7c0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2d7d0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2d7e0 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2d7f0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2d800 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2d810 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2d820 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2d830 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2d840 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2d850 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2d860 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2d870 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2d880 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2d890 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2d8a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d8b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2d8c0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2d8d0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
2d8e0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
2d8f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
2d900 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
2d910 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
2d920 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
2d930 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d940 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
2d950 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2d960 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
2d970 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
2d980 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
2d990 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
2d9a0 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
2d9b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
2d9c0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2d9d0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2d9e0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2d9f0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2da00 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2da10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2da20 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2da30 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2da40 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2da50 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2da60 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2da70 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2da80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2da90 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2daa0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2dab0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2dac0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2dad0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2dae0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2daf0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2db00 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2db10 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
2db20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2db30 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2db40 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2db50 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2db60 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2db70 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2db80 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
2db90 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
2dba0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
2dbb0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
2dbc0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
2dbd0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
2dbe0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
2dbf0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
2dc00 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
2dc10 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
2dc20 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
2dc30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2dc40 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2dc50 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2dc60 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2dc70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2dc80 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2dc90 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
2dca0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2dcb0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
2dcc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
2dcd0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2dce0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2dcf0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2dd00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2dd10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2dd20 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2dd30 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2dd40 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
2dd50 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2dd60 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2dd70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2dd80 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2dd90 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2dda0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2ddb0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2ddc0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2ddd0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
2dde0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2ddf0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2de00 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2de10 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2de20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2de30 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2de40 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2de50 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2de60 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2de70 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
2de80 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2de90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2dea0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2deb0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2dec0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2ded0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2dee0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2def0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2df00 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2df10 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2df20 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2df30 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2df40 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2df50 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2df60 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2df70 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2df80 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2df90 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2dfa0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2dfb0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2dfc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2dfd0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2dfe0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2dff0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2e000 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2e010 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2e020 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2e030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e040 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2e050 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2e060 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
2e070 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e080 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
2e090 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
2e0a0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
2e0b0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
2e0c0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2e0d0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
2e0e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e0f0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2e100 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e110 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2e120 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2e130 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2e140 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2e150 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
2e160 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
2e170 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
2e180 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
2e190 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
2e1a0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
2e1b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
2e1c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e1d0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
2e1e0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
2e1f0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
2e200 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2e210 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2e220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e230 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
2e240 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2e250 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2e260 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2e270 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2e280 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
2e290 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
2e2a0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
2e2b0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
2e2c0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
2e2d0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
2e2e0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
2e2f0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
2e300 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2e310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2e320 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
2e330 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
2e340 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2e350 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e360 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2e370 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
2e380 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
2e390 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
2e3a0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
2e3b0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2e3c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2e3d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2e3e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2e3f0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
2e400 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2e410 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2e420 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e430 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2e440 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e450 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
2e460 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
2e470 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2e480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2e490 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2e4a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e4b0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2e4c0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2e4d0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2e4e0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2e4f0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2e500 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
2e510 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2e520 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2e530 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2e540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2e550 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2e560 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2e570 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2e580 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2e590 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
2e5a0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
2e5b0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
2e5c0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2e5d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2e5e0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
2e5f0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2e600 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2e610 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2e620 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2e630 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
2e640 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
2e650 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2e660 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2e670 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2e680 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2e690 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2e6a0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2e6b0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
2e6c0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
2e6d0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
2e6e0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
2e6f0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2e700 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2e710 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2e720 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2e730 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
2e740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2e750 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
2e760 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2e770 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
2e780 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
2e790 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
2e7a0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2e7b0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
2e7c0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
2e7d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2e7e0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2e7f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e800 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
2e810 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
2e820 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
2e830 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2e840 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
2e850 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
2e860 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
2e870 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
2e880 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
2e890 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
2e8a0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
2e8b0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
2e8c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e8d0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
2e8e0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
2e8f0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
2e900 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
2e910 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
2e920 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
2e930 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
2e940 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2e950 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2e960 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
2e970 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2e980 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2e990 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2e9a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2e9b0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
2e9c0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
2e9d0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
2e9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e9f0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
2ea00 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2ea10 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2ea20 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2ea30 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2ea40 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2ea50 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
2ea60 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
2ea70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2ea80 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
2ea90 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2eaa0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2eab0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2eac0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
2ead0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
2eae0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
2eaf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2eb00 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2eb10 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2eb20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2eb30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eb40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2eb50 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2eb60 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2eb70 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2eb80 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2eb90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eba0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
2ebb0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ebc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2ebd0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2ebe0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ebf0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2ec00 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ec10 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2ec20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2ec30 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2ec40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2ec50 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
2ec60 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2ec70 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2ec80 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2ec90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2eca0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
2ecb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ecc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
2ecd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ece0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
2ecf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ed00 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
2ed10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ed20 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
2ed30 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
2ed40 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
2ed50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ed60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2ed70 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
2ed80 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
2ed90 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
2eda0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
2edb0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
2edc0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
2edd0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
2ede0 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
2edf0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
2ee00 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2ee10 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2ee20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ee30 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2ee40 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2ee50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ee60 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2ee70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2ee80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2ee90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2eea0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2eeb0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2eec0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2eed0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2eee0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2eef0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
2ef00 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2ef10 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2ef20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2ef30 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2ef40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2ef50 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2ef60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2ef70 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2ef80 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2ef90 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2efa0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2efb0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2efc0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2efd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2efe0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2eff0 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
2f000 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2f010 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2f020 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2f030 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
2f040 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f050 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
2f060 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2f070 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
2f080 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
2f090 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
2f0a0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
2f0b0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
2f0c0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2f0d0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2f0e0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2f0f0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2f100 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2f110 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2f120 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
2f130 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f140 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2f150 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2f160 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
2f170 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
2f180 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
2f190 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2f1a0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
2f1b0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2f1c0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
2f1d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
2f1e0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
2f1f0 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
2f200 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
2f210 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
2f220 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2f230 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2f240 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2f250 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2f260 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2f270 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2f280 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2f290 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2f2a0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2f2b0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2f2c0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2f2d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2f2e0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2f2f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2f300 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2f310 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2f320 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2f330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f340 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2f350 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f360 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2f370 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f390 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
2f3a0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2f3b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f3c0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
2f3d0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2f3e0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
2f3f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2f400 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
2f410 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2f420 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2f430 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
2f440 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f450 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2f460 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2f470 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2f480 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2f490 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2f4a0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2f4b0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2f4c0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
2f4d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2f4e0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
2f4f0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
2f500 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2f510 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f520 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
2f530 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
2f540 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
2f550 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f560 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
2f570 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
2f580 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
2f590 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2f5a0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
2f5b0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
2f5c0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
2f5d0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
2f5e0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
2f5f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f600 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
2f610 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2f620 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
2f630 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
2f640 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2f650 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2f660 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2f670 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2f680 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2f690 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2f6a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2f6b0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2f6c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2f6d0 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2f6e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2f6f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f700 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2f710 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2f720 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f730 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f740 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2f750 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2f760 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2f770 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2f780 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2f790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f7a0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2f7b0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2f7c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f7d0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2f7e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2f7f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2f800 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2f810 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2f820 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2f830 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2f840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2f850 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2f860 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2f870 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2f880 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2f890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f8a0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2f8b0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2f8c0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2f8d0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2f8e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f8f0 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2f900 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2f910 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2f920 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2f930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f940 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2f950 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2f960 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2f970 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2f980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f990 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2f9a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2f9b0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2f9c0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2f9d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2f9e0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2f9f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2fa00 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2fa10 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2fa20 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2fa30 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2fa40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fa50 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2fa60 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
2fa70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2fa80 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
2fa90 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
2faa0 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
2fab0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2fac0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2fad0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2fae0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
2faf0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2fb00 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2fb10 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
2fb20 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
2fb30 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2fb40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
2fb50 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
2fb60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
2fb70 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
2fb80 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
2fb90 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
2fba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2fbb0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
2fbc0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
2fbd0 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
2fbe0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
2fbf0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
2fc00 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
2fc10 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
2fc20 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
2fc30 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
2fc40 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
2fc50 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
2fc60 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
2fc70 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
2fc80 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
2fc90 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
2fca0 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
2fcb0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2fcc0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
2fcd0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
2fce0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2fcf0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
2fd00 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
2fd10 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
2fd20 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
2fd30 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2fd40 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
2fd50 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
2fd60 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
2fd70 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
2fd80 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
2fd90 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
2fda0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2fdb0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
2fdc0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
2fdd0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
2fde0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
2fdf0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
2fe00 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
2fe10 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
2fe20 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
2fe30 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
2fe40 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
2fe50 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
2fe60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2fe70 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
2fe80 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
2fe90 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2fea0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
2feb0 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
2fec0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2fed0 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
2fee0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
2fef0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2ff00 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2ff10 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
2ff20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ff30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2ff40 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
2ff50 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2ff60 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
2ff70 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
2ff80 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
2ff90 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
2ffa0 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
2ffb0 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
2ffc0 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
2ffd0 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
2ffe0 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
2fff0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
30000 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
30010 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
30020 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
30030 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
30040 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
30050 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
30060 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
30070 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
30080 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
30090 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
300a0 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
300b0 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
300c0 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
300d0 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
300e0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
300f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
30100 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
30110 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
30120 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
30130 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
30140 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
30150 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
30160 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
30170 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
30180 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
30190 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
301a0 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
301b0 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
301c0 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
301d0 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
301e0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
301f0 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
30200 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
30210 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
30220 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
30230 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
30240 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
30250 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
30260 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
30270 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
30280 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
30290 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
302a0 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
302b0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
302c0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
302d0 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
302e0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
302f0 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
30300 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
30310 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
30320 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
30330 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
30340 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
30350 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
30360 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
30370 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
30380 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
30390 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
303a0 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
303b0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
303c0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
303d0 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
303e0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
303f0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
30400 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
30410 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
30420 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
30430 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
30440 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
30450 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
30460 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
30470 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
30480 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
30490 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
304a0 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
304b0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
304c0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
304d0 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
304e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
304f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30500 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
30510 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
30520 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30530 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
30540 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
30550 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
30560 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
30570 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
30580 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
30590 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
305a0 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
305b0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
305c0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
305d0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
305e0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
305f0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
30600 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
30610 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
30620 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
30630 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
30640 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
30650 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
30660 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
30670 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
30680 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
30690 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
306a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
306b0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
306c0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
306d0 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
306e0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
306f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
30700 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
30710 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
30720 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
30730 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
30740 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
30750 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
30760 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30770 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
30780 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
30790 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
307a0 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
307b0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
307c0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
307d0 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
307e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
307f0 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
30800 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
30810 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
30820 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
30830 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
30840 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
30850 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
30860 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
30870 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
30880 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
30890 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
308a0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
308b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
308c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
308d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
308e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
308f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
30900 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
30910 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
30920 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
30930 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
30940 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
30950 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30960 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
30970 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
30980 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
30990 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
309a0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
309b0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
309c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
309d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
309e0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
309f0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
30a00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
30a10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
30a20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
30a30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
30a40 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
30a50 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
30a60 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
30a70 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
30a80 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
30a90 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
30aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
30ab0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
30ac0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
30ad0 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
30ae0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
30af0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
30b00 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
30b10 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
30b20 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
30b30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
30b40 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
30b50 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
30b60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30b70 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
30b80 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
30b90 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
30ba0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
30bb0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
30bc0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
30bd0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
30be0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
30bf0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
30c00 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
30c10 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
30c20 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
30c30 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
30c40 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
30c50 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
30c60 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
30c70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
30c80 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
30c90 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
30ca0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
30cb0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
30cc0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
30cd0 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
30ce0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
30cf0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
30d00 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
30d10 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
30d20 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
30d30 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
30d40 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
30d50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
30d60 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
30d70 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
30d80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
30d90 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
30da0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
30db0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
30dc0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
30dd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
30de0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
30df0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
30e00 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
30e10 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
30e20 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
30e30 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
30e40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
30e50 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
30e60 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
30e70 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
30e80 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
30e90 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
30ea0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
30eb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
30ec0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
30ed0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
30ee0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
30ef0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
30f00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
30f10 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
30f20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
30f30 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
30f40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30f50 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
30f60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30f70 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
30f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
30f90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
30fa0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30fb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
30fc0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
30fd0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
30fe0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
30ff0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
31000 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
31010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
31020 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
31030 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
31040 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
31050 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
31060 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
31070 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
31080 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
31090 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
310a0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
310b0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
310c0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
310d0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
310e0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
310f0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
31100 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
31110 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
31120 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
31130 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
31140 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
31150 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
31160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
31170 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
31180 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
31190 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
311a0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
311b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
311c0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
311d0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
311e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
311f0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
31200 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
31210 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
31220 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
31230 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
31240 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
31250 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
31260 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
31270 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
31280 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
31290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
312a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
312b0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
312c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
312d0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
312e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
312f0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
31300 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
31310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
31330 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
31340 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
31350 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
31360 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
31370 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
31380 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
31390 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
313a0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
313b0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
313c0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
313d0 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
313e0 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
313f0 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
31400 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
31410 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
31420 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
31430 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
31440 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
31450 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
31460 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
31470 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
31480 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
31490 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
314a0 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
314b0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
314c0 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
314d0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
314e0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
314f0 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
31500 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
31510 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
31520 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
31530 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
31540 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
31550 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
31560 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
31570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31580 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
31590 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
315a0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
315b0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
315c0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
315d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
315e0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
315f0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
31600 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
31610 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
31620 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
31630 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
31640 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
31650 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
31660 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
31670 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
31680 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
31690 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
316a0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
316b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
316c0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
316d0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
316e0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
316f0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
31700 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
31710 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
31720 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
31730 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
31740 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
31750 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
31760 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
31770 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
31780 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
31790 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
317a0 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
317b0 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
317c0 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
317d0 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
317e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
317f0 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
31800 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
31810 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
31820 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
31830 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
31840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31850 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
31860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
31870 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
31880 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
31890 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
318a0 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
318b0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
318c0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
318d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
318e0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
318f0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
31900 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
31910 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
31920 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
31930 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
31940 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
31950 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
31960 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
31970 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
31980 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
31990 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
319a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
319b0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
319c0 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
319d0 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
319e0 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
319f0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
31a00 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
31a10 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
31a20 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
31a30 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
31a40 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
31a50 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
31a60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
31a70 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
31a80 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
31a90 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
31aa0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
31ab0 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
31ac0 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
31ad0 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
31ae0 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
31af0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
31b00 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
31b10 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
31b20 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
31b30 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
31b40 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
31b50 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
31b60 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
31b70 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
31b80 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
31b90 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
31ba0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
31bb0 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
31bc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
31bd0 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
31be0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
31bf0 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
31c00 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
31c10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
31c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
31c30 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
31c40 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
31c50 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
31c60 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
31c70 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
31c80 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
31c90 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
31ca0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
31cb0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
31cc0 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
31cd0 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
31ce0 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
31cf0 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
31d00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
31d10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
31d20 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
31d30 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
31d40 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
31d50 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
31d60 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
31d70 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
31d80 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
31d90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
31da0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
31db0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
31dc0 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
31dd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
31de0 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
31df0 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
31e00 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
31e10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
31e20 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
31e30 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
31e40 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
31e50 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
31e60 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
31e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e80 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
31e90 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
31ea0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
31eb0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
31ec0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
31ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
31ee0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
31ef0 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
31f00 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
31f10 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
31f20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
31f30 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
31f40 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
31f50 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
31f60 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
31f70 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
31f80 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
31f90 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
31fa0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
31fb0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
31fc0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
31fd0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
31fe0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
31ff0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
32000 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
32010 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
32020 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
32030 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
32040 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
32050 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
32060 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
32070 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
32080 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
32090 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
320a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
320b0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
320c0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
320d0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
320e0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
320f0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
32100 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
32110 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
32120 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
32130 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
32140 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
32150 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
32160 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
32170 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
32180 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
32190 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
321a0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
321b0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
321c0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
321d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
321e0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
321f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32200 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
32210 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
32220 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
32230 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
32240 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
32250 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32260 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
32270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
32280 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
32290 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
322a0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
322b0 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
322c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
322d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
322e0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
322f0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
32300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
32310 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
32320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
32330 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
32340 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
32350 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
32360 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
32370 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
32380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32390 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
323a0 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
323b0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
323c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
323d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
323e0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
323f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32400 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
32410 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32420 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
32430 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
32440 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
32450 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
32460 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
32470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32480 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
32490 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
324a0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
324b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
324c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
324d0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
324e0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
324f0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
32500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32510 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
32520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32530 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
32540 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
32550 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
32560 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
32570 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
32580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
32590 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
325a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
325b0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
325c0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
325d0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
325e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
325f0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
32600 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
32610 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
32620 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
32630 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
32640 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
32650 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32660 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32670 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
32680 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
32690 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
326a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
326b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
326c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
326d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
326e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
326f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
32700 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
32710 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
32720 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
32730 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
32740 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
32750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
32760 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
32770 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
32780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
32790 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
327a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
327b0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
327c0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
327d0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
327e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
327f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
32800 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
32810 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
32820 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
32830 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
32840 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
32850 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
32860 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
32870 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
32880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32890 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
328a0 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
328b0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
328c0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
328d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
328e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
328f0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
32900 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
32910 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
32920 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
32930 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
32940 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
32950 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
32960 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
32970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
32980 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
32990 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
329a0 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
329b0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
329c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
329d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
329e0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
329f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32a00 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
32a10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
32a20 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
32a30 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
32a40 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
32a50 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
32a60 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
32a70 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
32a80 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
32a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32aa0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
32ab0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
32ac0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
32ad0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
32ae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
32af0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
32b00 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
32b10 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
32b20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
32b30 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
32b40 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
32b50 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
32b60 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
32b70 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
32b80 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
32b90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32ba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
32bb0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
32bc0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
32bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
32be0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
32bf0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
32c00 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
32c10 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
32c20 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
32c30 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
32c40 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
32c50 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
32c60 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
32c70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
32c80 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
32c90 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
32ca0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
32cb0 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
32cc0 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
32cd0 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
32ce0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
32cf0 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
32d00 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
32d10 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
32d20 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
32d30 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
32d40 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
32d50 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
32d60 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
32d70 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
32d80 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
32d90 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
32da0 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
32db0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
32dc0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
32dd0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
32de0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
32df0 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
32e00 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
32e10 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
32e20 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
32e30 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
32e40 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
32e50 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
32e60 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
32e70 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
32e80 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
32e90 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
32ea0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
32eb0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
32ec0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
32ed0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
32ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32ef0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
32f00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
32f10 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
32f20 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61  _hook()] interfa
32f30 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ce..*/.void *sql
32f40 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
32f50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
32f60 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
32f70 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
32f80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
32f90 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
32fa0 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
32fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32fc0 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
32fd0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
32fe0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
32ff0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
33000 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
33010 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
33020 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
33030 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
33040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33050 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
33060 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
33070 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
33080 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
33090 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
330a0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
330b0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
330c0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
330d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
330e0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
330f0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
33100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
33110 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
33120 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
33130 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
33140 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
33150 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
33160 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
33170 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
33180 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
33190 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
331a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
331b0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
331c0 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
331d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
331e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
331f0 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
33200 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
33210 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
33220 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
33230 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
33240 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
33250 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
33260 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
33270 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
33280 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
33290 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
332a0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
332b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
332c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
332d0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
332e0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
332f0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
33300 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
33310 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
33320 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61  ** ^The final ca
33330 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
33340 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
33350 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e  of the row..** ^
33360 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
33370 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
33380 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66  s the [rowid] af
33390 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
333a0 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
333b0 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68  * ^(The update h
333c0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
333d0 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
333e0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
333f0 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
33400 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
33410 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
33420 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a  quence).)^.**.**
33430 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74   ^In the current
33440 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
33450 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
33460 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  .** is not invok
33470 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74  ed when duplicat
33480 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  ion rows are del
33490 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20  eted because of 
334a0 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49  an.** [ON CONFLI
334b0 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  CT | ON CONFLICT
334c0 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65   REPLACE] clause
334d0 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75  .  ^Nor is the u
334e0 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e  pdate hook.** in
334f0 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20  voked when rows 
33500 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e  are deleted usin
33510 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20  g the [truncate 
33520 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a  optimization]..*
33530 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73  * The exceptions
33540 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73   defined in this
33550 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74   paragraph might
33560 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
33570 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
33580 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
33590 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
335a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
335b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
335c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
335d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
335e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
335f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
33600 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
33610 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
33620 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
33630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33640 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
33650 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
33660 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
33670 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
33680 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
33690 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
336a0 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
336b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
336c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
336d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
336e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
336f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
33700 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
33710 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
33720 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
33730 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
33740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33750 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43  _update_hook(D,C
33760 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ,P) function.** 
33770 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
33780 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
33790 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a  previous call.**
337a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
337b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
337c0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
337d0 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
337e0 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  all on D..**.** 
337f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
33800 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
33810 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
33820 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33830 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
33840 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
33850 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
33860 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
33870 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
33880 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
33890 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
338a0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
338b0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
338c0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
338d0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
338e0 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
338f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
33900 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20  ed cache}.**.** 
33910 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
33920 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
33930 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
33940 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
33950 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
33960 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
33970 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
33980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33990 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
339a0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
339b0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
339c0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
339d0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
339e0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
339f0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
33a00 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
33a10 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
33a20 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
33a30 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
33a40 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
33a50 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
33a60 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
33a70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
33a80 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
33a90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
33aa0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
33ab0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
33ac0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
33ad0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
33ae0 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
33af0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
33b00 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
33b10 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
33b20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
33b30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
33b40 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
33b50 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
33b60 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
33b70 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
33b80 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
33b90 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
33ba0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
33bb0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
33bc0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
33bd0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
33be0 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
33bf0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
33c00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
33c10 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
33c20 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
33c30 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
33c40 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
33c50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
33c60 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
33c70 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
33c80 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
33c90 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
33ca0 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
33cb0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
33cc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
33cd0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
33ce0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
33cf0 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
33d00 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
33d10 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
33d20 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
33d30 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
33d40 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
33d50 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Mode].*/.int sql
33d60 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
33d70 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
33d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33d90 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
33da0 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a  Heap Memory.**.*
33db0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33dc0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
33dd0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
33de0 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
33df0 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
33e00 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
33e10 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
33e20 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
33e30 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
33e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
33e50 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20  brary.   Memory 
33e60 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
33e70 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
33e80 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
33e90 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
33ea0 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
33eb0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
33ec0 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   ^sqlite3_releas
33ed0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
33ee0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
33ef0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
33f00 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
33f10 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
33f20 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
33f30 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
33f40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33f50 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
33f60 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e  ) routine is a n
33f70 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a  o-op returning z
33f80 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  ero.** if SQLite
33f90 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64   is not compiled
33fa0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   with [SQLITE_EN
33fb0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
33fc0 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  GEMENT]..*/.int 
33fd0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
33fe0 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
33ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
34000 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
34010 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20  Heap Size.**.** 
34020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66  ^The sqlite3_sof
34030 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
34040 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34050 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74  and/or queries t
34060 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74  he.** soft limit
34070 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
34080 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
34090 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
340a0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
340b0 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65  * ^SQLite strive
340c0 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d  s to keep heap m
340d0 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f  emory utilizatio
340e0 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74  n below the soft
340f0 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62   heap.** limit b
34100 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e  y reducing the n
34110 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68  umber of pages h
34120 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20  eld in the page 
34130 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70  cache.** as heap
34140 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61   memory usages a
34150 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69  pproaches the li
34160 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66  mit..** ^The sof
34170 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
34180 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65  "soft" because e
34190 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74  ven though SQLit
341a0 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61  e strives to sta
341b0 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c  y.** below the l
341c0 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78  imit, it will ex
341d0 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72  ceed the limit r
341e0 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72  ather than gener
341f0 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54  ate.** an [SQLIT
34200 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20  E_NOMEM] error. 
34210 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
34220 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
34230 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69  imit .** is advi
34240 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
34250 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c   ^The return val
34260 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
34270 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
34280 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20  4() is the size 
34290 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  of.** the soft h
342a0 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20  eap limit prior 
342b0 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49  to the call.  ^I
342c0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
342d0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
342e0 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69  then no change i
342f0 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f  s made to the so
34300 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
34310 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65  Hence, the curre
34320 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  nt.** size of th
34330 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
34340 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
34350 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a  ned by invoking.
34360 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  ** sqlite3_soft_
34370 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77  heap_limit64() w
34380 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61  ith a negative a
34390 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
343a0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
343b0 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74  N is zero then t
343c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
343d0 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  it is disabled..
343e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74  **.** ^(The soft
343f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e   heap limit is n
34400 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74  ot enforced in t
34410 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
34420 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20  mentation.** if 
34430 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66  one or more of f
34440 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69  ollowing conditi
34450 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a  ons are true:.**
34460 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
34470 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   The soft heap l
34480 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a  imit is set to z
34490 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d  ero..** <li> Mem
344a0 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
344b0 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  s disabled using
344c0 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
344d0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73  f the.**      [s
344e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
344f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
34500 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74  MSTATUS],...) st
34510 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  art-time option 
34520 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  and.**      the 
34530 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
34540 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69  MEMSTATUS] compi
34550 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
34560 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72  ** <li> An alter
34570 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68  native page cach
34580 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34590 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75 73   is specified us
345a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
345b0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
345c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
345d0 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69  HE],...)..** <li
345e0 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65  > The page cache
345f0 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20   allocates from 
34600 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70  its own memory p
34610 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ool supplied.** 
34620 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
34630 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
34640 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
34650 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74  E],...) rather t
34660 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d  han.**      from
34670 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f   the heap..** </
34680 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  ul>)^.**.** Begi
34690 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
346a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c  e version 3.7.3,
346b0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
346c0 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
346d0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
346e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
346f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
34700 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
34710 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  EMENT].** compil
34720 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
34730 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20   invoked.  With 
34740 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
34750 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
34760 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  ],.** the soft h
34770 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
34780 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d  orced on every m
34790 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
347a0 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53  .  Without.** [S
347b0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
347c0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
347d0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
347e0 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66  imit is only enf
347f0 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65  orced.** when me
34800 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
34810 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
34820 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75  che.  Testing su
34830 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61  ggests that beca
34840 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20  use.** the page 
34850 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65  cache is the pre
34860 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20  dominate memory 
34870 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20  user in SQLite, 
34880 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
34890 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76  ions will achiev
348a0 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20  e adequate soft 
348b0 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72  heap limit enfor
348c0 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a  cement without.*
348d0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51  * the use of [SQ
348e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
348f0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
34900 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d  **.** The circum
34910 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68  stances under wh
34920 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ich SQLite will 
34930 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74  enforce the soft
34940 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a   heap limit may.
34950 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75  ** changes in fu
34960 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
34970 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69   SQLite..*/.sqli
34980 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
34990 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
349a0 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64(sqlite3_int6
349b0 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  4 N);../*.** CAP
349c0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
349d0 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69  d Soft Heap Limi
349e0 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44  t Interface.** D
349f0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
34a00 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63  This is a deprec
34a10 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  ated version of 
34a20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  the [sqlite3_sof
34a30 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
34a40 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
34a50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
34a60 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69   provided for hi
34a70 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
34a80 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20  bility.** only. 
34a90 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61   All new applica
34aa0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65  tions should use
34ab0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
34ac0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
34ad0 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  64()] interface 
34ae0 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73  rather than this
34af0 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   one..*/.SQLITE_
34b00 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
34b10 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
34b20 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
34b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34b40 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
34b50 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
34b60 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
34b70 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
34b80 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
34b90 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
34ba0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
34bb0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
34bc0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
34bd0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
34be0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34bf0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
34c00 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
34c10 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
34c20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
34c30 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
34c40 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
34c50 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
34c60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
34c70 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
34c80 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
34c90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
34ca0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
34cb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
34cc0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
34cd0 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
34ce0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
34cf0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
34d00 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
34d10 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
34d20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
34d30 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
34d40 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
34d50 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
34d60 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
34d70 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
34d80 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
34d90 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
34da0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
34db0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
34dc0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
34dd0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
34de0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
34df0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
34e00 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
34e10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
34e20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
34e30 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
34e40 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
34e50 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
34e60 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
34e70 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
34e80 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
34e90 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
34ea0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
34eb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
34ec0 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
34ed0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
34ee0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
34ef0 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
34f00 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
34f10 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
34f20 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
34f30 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
34f40 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
34f50 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
34f60 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
34f70 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
34f80 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
34f90 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
34fa0 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
34fb0 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
34fc0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
34fd0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
34fe0 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
34ff0 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
35000 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
35010 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
35020 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
35030 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
35040 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
35050 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
35060 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
35070 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
35080 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
35090 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
350a0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
350b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
350c0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
350d0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
350e0 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
350f0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
35100 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
35110 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
35120 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
35130 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
35140 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
35150 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
35160 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
35170 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
35180 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
35190 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
351a0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
351b0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
351c0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
351d0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
351e0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
351f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
35200 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
35210 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
35220 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
35230 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
35240 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
35250 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
35260 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
35270 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
35280 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
35290 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
352a0 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
352b0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
352c0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
352d0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
352e0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
352f0 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
35300 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
35310 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
35320 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
35330 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
35340 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
35350 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
35360 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
35370 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
35380 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
35390 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
353a0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
353b0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
353c0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
353d0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
353e0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
353f0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
35400 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
35410 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
35420 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
35430 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
35440 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
35450 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
35460 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
35470 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
35480 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
35490 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
354a0 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
354b0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
354c0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
354d0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
354e0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
354f0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
35500 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
35510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35520 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
35530 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
35540 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
35550 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
35560 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
35570 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
35580 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
35590 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
355a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
355b0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
355c0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
355d0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
355e0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
355f0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
35600 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35620 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
35630 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
35640 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
35650 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
35660 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
35670 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
35680 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
35690 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
356a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
356b0 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
356c0 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
356d0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
356e0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
356f0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
35700 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
35710 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
35720 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
35730 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
35740 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
35750 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
35760 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
35770 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
35780 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
35790 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
357a0 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
357b0 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
357c0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
357d0 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
357e0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
357f0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
35800 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
35810 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
35820 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
35830 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
35840 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
35850 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
35860 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
35870 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
35880 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
35890 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
358a0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   file..**.** ^Th
358b0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
358c0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
358d0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
358e0 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69   load an.** SQLi
358f0 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
35900 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
35910 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
35920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74  ..**.** ^The ent
35930 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
35940 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79  c..** ^zProc may
35950 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
35960 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
35970 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
35980 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20  .** defaults to 
35990 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
359a0 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68  on_init"..** ^Th
359b0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
359c0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
359d0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
359e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
359f0 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
35a00 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
35a10 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
35a20 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  g..** ^If an err
35a30 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
35a40 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
35a50 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71   then the.** [sq
35a60 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
35a70 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
35a80 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
35a90 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72  to.** fill *pzEr
35aa0 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
35ab0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
35ac0 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
35ad0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
35ae0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35af0 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ]. The calling f
35b00 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  unction.** shoul
35b10 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
35b20 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
35b30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
35b40 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
35b50 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
35b60 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
35b70 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  * [sqlite3_enabl
35b80 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
35b90 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  ()] prior to cal
35ba0 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a  ling this API,.*
35bb0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  * otherwise an e
35bc0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
35bd0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
35be0 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
35bf0 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
35c00 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
35c10 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
35c20 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
35c30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35c40 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
35c50 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
35c60 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
35c70 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
35c80 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
35c90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
35ca0 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
35cb0 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
35cc0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
35cd0 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
35ce0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
35cf0 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
35d00 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
35d10 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
35d20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
35d30 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
35d40 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
35d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
35d60 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
35d70 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
35d80 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
35d90 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
35da0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
35db0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
35dc0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
35dd0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
35de0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
35df0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
35e00 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
35e10 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
35e20 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
35e30 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
35e40 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
35e50 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
35e60 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
35e70 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
35e80 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
35e90 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
35ea0 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45  nd off..**.** ^E
35eb0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
35ec0 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
35ed0 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
35ee0 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74  1863..** ^Call t
35ef0 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
35f00 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
35f10 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  () routine with 
35f20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74  onoff==1.** to t
35f30 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
35f40 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
35f50 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
35f60 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74  =0 to turn.** it
35f70 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
35f80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35f90 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
35fa0 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
35fb0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
35fc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35fd0 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
35fe0 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69  ad Statically Li
35ff0 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a  nked Extensions.
36000 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
36010 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
36020 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66   xEntryPoint() f
36030 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
36040 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63  voked for.** eac
36050 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
36060 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
36070 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
36080 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74  e idea here is t
36090 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  hat.** xEntryPoi
360a0 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72  nt() is the entr
360b0 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74  y point for a st
360c0 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
360d0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
360e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62  .** that is to b
360f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
36100 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20  loaded into all 
36110 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
36120 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nections..**.** 
36130 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68  ^(Even though th
36140 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f  e function proto
36150 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20  type shows that 
36160 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61  xEntryPoint() ta
36170 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65  kes.** no argume
36180 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20  nts and returns 
36190 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76  void, SQLite inv
361a0 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74  okes xEntryPoint
361b0 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a  () with three.**
361c0 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65   arguments and e
361d0 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67  xpects and integ
361e0 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20  er result as if 
361f0 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66  the signature of
36200 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f   the.** entry po
36210 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c  int where as fol
36220 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
36230 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
36240 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e   &nbsp;  int xEn
36250 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62  tryPoint(.** &nb
36260 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a  sp;    sqlite3 *
36270 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  db,.** &nbsp;   
36280 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
36290 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70  ErrMsg,.** &nbsp
362a0 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63  ;    const struc
362b0 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
362c0 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a  utines *pThunk.*
362d0 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20  * &nbsp;  );.** 
362e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
362f0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  te>)^.**.** If t
36300 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72  he xEntryPoint r
36310 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72  outine encounter
36320 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73  s an error, it s
36330 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72  hould make *pzEr
36340 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  rMsg.** point to
36350 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
36360 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f  error message (o
36370 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36380 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
36390 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20  ).** and return 
363a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
363b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53  error code].  ^S
363c0 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68  QLite ensures th
363d0 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  at *pzErrMsg.** 
363e0 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63  is NULL before c
363f0 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72  alling the xEntr
36400 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69  yPoint().  ^SQLi
36410 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  te will invoke.*
36420 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
36430 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20  )] on *pzErrMsg 
36440 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e  after xEntryPoin
36450 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49  t() returns.  ^I
36460 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50  f any.** xEntryP
36470 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61  oint() returns a
36480 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71  n error, the [sq
36490 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
364a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
364b0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
364c0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c  3_open_v2()] cal
364d0 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  l that provoked 
364e0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  the xEntryPoint(
364f0 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a  ) will fail..**.
36500 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
36510 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
36520 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e  on(X) with an en
36530 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74  try point X that
36540 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f   is already.** o
36550 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75  n the list of au
36560 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
36570 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  ns is a harmless
36580 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72   no-op. ^No entr
36590 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20  y point.** will 
365a0 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74  be called more t
365b0 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  han once for eac
365c0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
365d0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70  ction that is op
365e0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ened..**.** See 
365f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72  also: [sqlite3_r
36600 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
36610 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ion()]..*/.int s
36620 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
36630 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e  nsion(void (*xEn
36640 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29  tryPoint)(void))
36650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36660 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
36670 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
36680 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ding.**.** ^This
36690 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62   interface disab
366a0 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69  les all automati
366b0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65  c extensions pre
366c0 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73  viously.** regis
366d0 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
366e0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
366f0 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  ion()]..*/.void 
36700 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
36710 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
36720 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  d);../*.** The i
36730 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
36740 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
36750 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
36760 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
36770 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
36780 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
36790 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
367a0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
367b0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
367c0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
367d0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
367e0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
367f0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
36800 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
36810 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
36820 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
36830 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
36840 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
36850 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
36860 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
36870 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
36880 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
36890 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
368a0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
368b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
368c0 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
368d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
368e0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
368f0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
36900 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36910 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
36920 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
36930 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
36940 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
36950 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
36960 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
36970 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36980 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
36990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
369a0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
369b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
369c0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
369d0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
369e0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54   module}.**.** T
369f0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
36a00 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
36a10 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a "virtual table
36a20 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65   module", .** de
36a30 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d  fines the implem
36a40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76  entation of a [v
36a50 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20  irtual tables]. 
36a60 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74   .** This struct
36a70 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73  ure consists mos
36a80 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
36a90 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
36aa0 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20  *.** ^A virtual 
36ab0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20  table module is 
36ac0 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69  created by filli
36ad0 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65  ng in a persiste
36ae0 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  nt.** instance o
36af0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
36b00 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70   and passing a p
36b10 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69  ointer to that i
36b20 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73  nstance.** to [s
36b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36b40 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  dule()] or [sqli
36b50 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36b60 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  e_v2()]..** ^The
36b70 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
36b80 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
36b90 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
36ba0 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
36bb0 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
36bc0 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
36bd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
36be0 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
36bf0 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
36c00 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
36c10 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
36c20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
36c30 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
36c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
36c50 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
36c60 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
36c70 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
36c80 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
36c90 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
36ca0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
36cb0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
36cc0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
36cd0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
36ce0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
36cf0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
36d00 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
36d10 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
36d20 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
36d30 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
36d40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
36d50 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
36d60 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
36d70 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
36d80 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
36d90 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
36da0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
36db0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
36dc0 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
36dd0 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
36de0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
36df0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
36e00 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
36e10 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
36e20 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
36e30 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
36e40 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
36e50 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
36e60 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
36e70 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
36e80 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
36e90 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
36ea0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
36eb0 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
36ec0 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
36ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
36ee0 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
36ef0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
36f00 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
36f10 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
36f20 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
36f30 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
36f40 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
36f50 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
36f60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
36f70 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
36f80 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
36f90 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
36fa0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
36fb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
36fc0 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
36fd0 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
36fe0 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
36ff0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
37000 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
37010 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
37020 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37030 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
37040 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
37050 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
37060 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
37070 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
37080 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
37090 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
370a0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
370b0 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
370c0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
370d0 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
370e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
370f0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
37100 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37110 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
37120 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37130 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37140 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
37150 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
37160 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
37170 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
37180 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
37190 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
371a0 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68 6f  ;.  /* The metho
371b0 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
371c0 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
371d0 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20 6f   sqlite_module o
371e0 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20 20  bject. Those .  
371f0 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  ** below are for
37200 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 67   version 2 and g
37210 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e 74  reater. */.  int
37220 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73   (*xSavepoint)(s
37230 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37240 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  ab, int);.  int 
37250 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c 69  (*xRelease)(sqli
37260 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
37270 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
37280 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69  RollbackTo)(sqli
37290 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
372a0 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   int);.};../*.**
372b0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
372c0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
372d0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  g Information.**
372e0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
372f0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
37300 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37310 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
37320 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
37330 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
37340 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66  ed as part.** of
37350 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
37360 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74  ble] interface t
37370 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
37380 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
37390 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
373a0 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74   from the [xBest
373b0 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64  Index].** method
373c0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
373d0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54  able module].  T
373e0 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
373f0 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
37400 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
37410 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
37420 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
37430 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
37440 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
37450 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
37460 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
37470 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74  .** ^(The aConst
37480 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
37490 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
374a0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
374b0 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  f the form:.**.*
374c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f  * <blockquote>co
374d0 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c  lumn OP expr</bl
374e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
374f0 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
37500 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
37510 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e  , or &gt;=.)^  ^
37520 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20  (The particular 
37530 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73  operator is.** s
37540 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72  tored in aConstr
37550 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20  aint[].op using 
37560 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53  one of the.** [S
37570 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
37580 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49  TRAINT_EQ | SQLI
37590 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
375a0 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a  INT_ values].)^.
375b0 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f  ** ^(The index o
375c0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
375d0 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
375e0 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
375f0 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72  mn.)^  ^(aConstr
37600 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
37610 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
37620 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
37630 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
37640 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
37650 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
37660 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
37670 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
37680 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a   it cannot.)^.**
37690 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a  .** ^The optimiz
376a0 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
376b0 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
376c0 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
376d0 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
376e0 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
376f0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
37700 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
37710 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
37720 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
37730 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
37740 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
37750 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
37760 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
37770 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^The aConstraint
37780 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
37790 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
377a0 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72  se terms that ar
377b0 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f  e.** relevant to
377c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
377d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
377e0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
377f0 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ** ^Information 
37800 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
37810 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
37820 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
37830 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d  ]..** ^Each term
37840 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
37850 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
37860 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
37870 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
37880 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
37890 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
378a0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
378b0 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
378c0 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
378d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
378e0 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
378f0 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20  ^If argvIndex>0 
37900 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
37910 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
37920 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37930 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
37940 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
37950 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
37960 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
37970 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66  y in argv.  ^(If
37980 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
37990 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
379a0 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
379b0 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
379c0 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
379d0 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
379e0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
379f0 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
37a00 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
37a10 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te.)^.**.** ^The
37a20 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
37a30 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
37a40 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
37a50 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
37a60 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
37a70 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65  ** ^[sqlite3_fre
37a80 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
37a90 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
37aa0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65  nd only if.** ne
37ab0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
37ac0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
37ad0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
37ae0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
37af0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
37b00 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
37b10 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
37b20 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
37b30 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
37b40 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
37b50 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
37b60 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
37b70 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
37b80 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
37b90 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
37ba0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
37bb0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
37bc0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
37bd0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
37be0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
37bf0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
37c00 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
37c10 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
37c20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
37c30 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
37c40 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
37c50 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
37c60 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
37c70 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
37c80 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
37c90 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
37ca0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
37cb0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
37cc0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
37cd0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
37ce0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
37cf0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
37d00 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
37d10 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
37d20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
37d30 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
37d40 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
37d50 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
37d60 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
37d70 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
37d80 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
37d90 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
37da0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
37db0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
37dc0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
37dd0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
37de0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
37df0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
37e00 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
37e10 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
37e20 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
37e30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
37e40 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
37e50 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
37e60 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
37e70 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
37e80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
37e90 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
37ea0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
37eb0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
37ec0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
37ed0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
37ee0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
37ef0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
37f00 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
37f10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
37f20 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
37f30 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
37f40 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
37f50 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
37f60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37f70 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
37f80 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
37f90 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
37fa0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
37fb0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
37fc0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
37fd0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
37fe0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
37ff0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
38000 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
38010 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
38020 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
38030 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
38040 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
38050 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
38060 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
38070 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
38080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38090 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
380a0 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
380b0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
380c0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
380d0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
380e0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
380f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
38100 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
38110 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
38120 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
38130 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
38140 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
38150 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
38160 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
38170 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
38180 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
38190 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
381a0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
381b0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
381c0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
381d0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
381e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
381f0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
38200 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65 72   Constraint Oper
38210 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  ator Codes.**.**
38220 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64 65   These macros de
38230 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77 65  fined the allowe
38240 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  d values for the
38250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64  .** [sqlite3_ind
38260 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72  ex_info].aConstr
38270 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e  aint[].op field.
38280 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65 70    Each value rep
38290 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70  resents.** an op
382a0 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20 70  erator that is p
382b0 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72 61  art of a constra
382c0 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65 20  int term in the 
382d0 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 0a  wHERE clause of.
382e0 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74 20  ** a query that 
382f0 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c 20  uses a [virtual 
38300 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69  table]..*/.#defi
38310 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
38320 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
38330 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
38340 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
38350 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
38360 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
38370 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
38380 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
38390 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
383a0 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
383b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
383c0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
383d0 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
383e0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
383f0 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
38400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38410 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
38420 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
38430 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tation.**.** ^Th
38440 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
38450 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
38460 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  r a new [virtual
38470 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e   table module] n
38480 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20  ame..** ^Module 
38490 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65  names must be re
384a0 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a  gistered before.
384b0 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65  ** creating a ne
384c0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
384d0 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75  ] using the modu
384e0 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73  le and before us
384f0 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73  ing a.** preexis
38500 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61  ting [virtual ta
38510 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64  ble] for the mod
38520 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ule..**.** ^The 
38530 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72  module name is r
38540 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65  egistered on the
38550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38560 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
38570 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
38580 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
38590 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  e name of the mo
385a0 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79  dule is given by
385b0 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20   the .** second 
385c0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
385d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
385e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
385f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
38600 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76  tation of the [v
38610 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
38620 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75  ule].   ^The fou
38630 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
38640 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
38650 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
38660 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
38670 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69  sed through.** i
38680 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65  nto the [xCreate
38690 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
386a0 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
386b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
386c0 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e  dule.** when a n
386d0 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
386e0 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65   is be being cre
386f0 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61  ated or reinitia
38700 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lized..**.** ^Th
38710 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
38720 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74  _module_v2() int
38730 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69 66  erface has a fif
38740 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  th parameter whi
38750 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
38760 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
38770 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65  or for the pClie
38780 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65  ntData.  ^SQLite
38790 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20   will.** invoke 
387a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
387b0 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69  unction (if it i
387c0 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e  s not NULL) when
387d0 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f   SQLite.** no lo
387e0 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70  nger needs the p
387f0 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74  ClientData point
38800 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  er.  ^The destru
38810 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  ctor will also.*
38820 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 66 20  * be invoked if 
38830 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c