/ Hex Artifact Content
Login

Artifact 8bbf8d9bc5f1a9474a633a2de7014506f1f06b90:


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: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5160: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5170: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5180: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
51a0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
51b0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
51c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
51d0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
51e0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
51f0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd 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 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5220: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5230: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5240: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5250: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5260: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5280: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5290: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
52a0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
52b0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
52d0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
52e0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
52f0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5300: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5320: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5330: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5340: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5350: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5370: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5380: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5390: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53b0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
53c0: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
53d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53f0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5400: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5410: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5430: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5440: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5450: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5460: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5480: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5490: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
54a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
54c0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
54d0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
54e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5500: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5510: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5520: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5530: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5540: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5550: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5560: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5580: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5590: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
55a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
55c0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
55d0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
55e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5600: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5610: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5620: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5640: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5650: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5660: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5670: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5690: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
56a0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
56b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
56c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
56e0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
56f0: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
5700: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5710: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5730: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
5740: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
5750: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5760: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5780: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
5790: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
57a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
57b0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
57c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
57d0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
57e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
57f0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5800: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
5810: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
5820: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
5830: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
5840: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
5850: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
5860: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
5870: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
5880: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
5890: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
58a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
58b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
58c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
58d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
58e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
58f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5900: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
5910: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
5920: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5930: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5940: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
5950: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
5960: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5970: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5980: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5990: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
59a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
59b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
59c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
59d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
59e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
59f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5a00: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5a10: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5a30: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
5a40: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
5a50: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
5a60: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
5a70: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5a80: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5a90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5aa0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5ab0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5ac0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5ad0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5ae0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5af0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5b00: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5b10: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5b20: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5b30: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5b40: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
5b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b80: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5ba0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
5bb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5bd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bf0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5c00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c10: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
5c20: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c40: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5c50: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c60: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5c70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c80: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
5c90: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5cb0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5cc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5cd0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5ce0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5cf0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5d00: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
5d10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5d20: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5d30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5d40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5d50: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5d60: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
5d70: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5d80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5d90: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
5da0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5dc0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
5dd0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
5de0: 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000800../*.** CA
5df0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5e00: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
5e10: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
5e20: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
5e30: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
5e40: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
5e50: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
5e60: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
5e70: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
5e80: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
5e90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
5ea0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
5eb0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5ec0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
5ed0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
5ee0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5ef0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5f10: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
5f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5f30: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
5f40: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
5f50: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5f60: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
5f70: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
5f80: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
5f90: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
5fa0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
5fb0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
5fc0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
5fd0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5fe0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
5ff0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6000: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6010: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6020: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6030: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6040: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6050: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6060: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6070: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6080: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6090: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
60a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
60b0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
60c0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
60d0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
60e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
60f0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6100: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6110: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6120: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6130: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6140: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6150: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6160: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6170: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6180: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6190: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
61a0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
61b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
61c0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
61d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
61e0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
61f0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6200: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6210: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6220: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6230: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6240: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6250: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6260: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6270: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6280: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6290: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
62a0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
62b0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
62c0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
62d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
62e0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
62f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6300: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6310: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6320: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6330: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6340: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6350: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6360: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6370: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6380: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6390: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
63a0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
63b0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
63c0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
63d0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
63e0: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
63f0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6400: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6410: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6420: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6430: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6440: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6450: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6460: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6470: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6490: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
64a0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
64b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
64c0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
64d0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
64e0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
64f0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6500: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6510: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6520: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6530: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6540: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6550: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6560: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6570: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6580: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6590: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
65a0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
65b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
65c0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
65d0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
65e0: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
65f0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6600: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6610: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6620: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6630: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6640: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6650: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6660: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6670: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6680: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6690: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
66a0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
66b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
66c0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
66d0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
66e0: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
66f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6700: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6710: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6720: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6730: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6740: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6750: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6760: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6770: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6780: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6790: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
67a0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
67b0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
67c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
67d0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
67e0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
67f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6800: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6810: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6820: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6830: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6840: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6850: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6860: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6870: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
6880: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
6890: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
68a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
68b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
68c0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
68d0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
68e0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
68f0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
6900: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6910: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
6920: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
6930: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
6940: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
6950: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
6960: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
6970: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
6980: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6990: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
69a0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
69b0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
69c0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
69d0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
69e0: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
69f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
6a00: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
6a10: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
6a20: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
6a30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
6a40: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
6a50: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
6a60: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6a70: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
6a80: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
6a90: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
6aa0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6ab0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
6ac0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
6ad0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
6ae0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
6af0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
6b00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
6b10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
6b20: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
6b30: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
6b40: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
6b50: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
6b60: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
6b70: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
6b80: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
6b90: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
6ba0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
6bb0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
6bc0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
6bd0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
6be0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
6bf0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
6c00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6c10: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
6c20: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6c30: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
6c40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6c50: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
6c60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6c70: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
6c80: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
6c90: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
6ca0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
6cb0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
6cc0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
6cd0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
6ce0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
6cf0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
6d00: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
6d10: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
6d20: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
6d30: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
6d40: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
6d50: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
6d60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
6d70: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
6d80: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
6d90: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
6da0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
6db0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
6dc0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
6dd0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
6de0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
6df0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
6e00: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
6e10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
6e20: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
6e30: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
6e40: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
6e50: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6e60: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
6e70: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
6e80: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
6e90: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
6ea0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
6eb0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
6ec0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
6ed0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
6ee0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
6ef0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
6f00: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
6f10: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
6f20: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
6f30: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
6f40: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
6f50: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
6f60: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
6f70: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
6f80: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
6f90: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
6fa0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
6fb0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
6fc0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
6fd0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
6fe0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
6ff0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7000: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7010: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7020: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7030: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7040: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7050: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7060: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7080: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7090: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
70a0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
70b0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
70c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
70d0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
70e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
70f0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7100: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7110: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7120: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7130: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7140: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7150: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7160: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7170: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7180: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7190: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
71a0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
71b0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
71c0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
71d0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
71e0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
71f0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7200: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7210: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7220: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7230: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7240: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7250: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7260: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7270: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7280: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7290: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
72a0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
72b0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
72c0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
72d0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
72e0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
72f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7300: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7310: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7320: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7330: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7340: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7350: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7360: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7370: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7380: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
73b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73c0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
73f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7400: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7410: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7420: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7430: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7440: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7450: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7460: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7470: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7480: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7490: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
74a0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
74b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
74c0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
74d0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
74e0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
74f0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7500: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7510: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7520: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7530: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7540: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7550: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7560: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7570: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7580: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7590: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
75a0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
75b0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
75c0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
75d0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
75e0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
75f0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7600: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7610: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7620: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7630: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7640: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7650: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7660: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7670: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7680: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7690: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
76a0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
76b0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
76c0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
76d0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
76e0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
76f0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7700: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7710: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7720: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7730: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7740: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7750: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7760: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7770: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7780: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7790: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
77a0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
77b0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
77c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
77d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
77e0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
77f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7800: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7810: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7820: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7830: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7840: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7850: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7860: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
7880: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7890: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
78a0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
78b0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
78c0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
78d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
78e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
78f0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
7900: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
7910: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
7920: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
7930: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7940: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7950: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
7960: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
7970: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
7980: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
7990: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
79a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
79b0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
79c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79d0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
79e0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
79f0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
7a00: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
7a10: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
7a20: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
7a30: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7a40: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
7a50: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
7a60: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
7a70: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
7a80: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
7a90: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
7aa0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
7ab0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
7ac0: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
7ad0: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
7ae0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
7af0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
7b00: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
7b10: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
7b20: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
7b30: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
7b40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
7b50: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
7b60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7b70: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
7b80: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b90: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7ba0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
7bb0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
7bc0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
7bd0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
7be0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
7bf0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
7c00: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
7c10: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
7c20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7c30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7c40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7c50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7c60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7c70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7c80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
7c90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7ca0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
7cb0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
7cc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7cd0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
7ce0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7cf0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7d00: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7d10: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7d20: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7d30: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7d40: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7d50: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7d60: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7d70: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7d80: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
7d90: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
7da0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7db0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7dc0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7dd0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7de0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7df0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7e00: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7e10: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7e20: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7e30: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7e40: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7e50: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7e60: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7e70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7e80: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
7e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7ea0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
7eb0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
7ec0: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
7ed0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
7ee0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
7ef0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
7f00: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
7f10: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
7f20: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
7f30: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
7f40: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
7f50: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
7f60: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
7f70: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
7f80: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
7f90: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
7fa0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
7fb0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
7fc0: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
7fd0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
7fe0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
7ff0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   faster..**.** T
8000: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8010: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8030: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8040: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8050: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8060: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8070: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8080: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8090: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
80a0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
80b0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
80c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
80d0: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
80e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
80f0: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8100: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8110: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8120: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8130: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8140: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8150: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8160: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8170: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
8180: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
8190: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
81a0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
81b0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
81c0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
81d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
81e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
81f0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8200: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
8210: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
8220: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
8230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
8240: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
8250: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
8260: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8270: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8280: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8290: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
82a0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
82b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
82c0: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
82d0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
82e0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
82f0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
8300: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
8310: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
8320: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
8330: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
8340: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
8350: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
8360: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8370: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
8380: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
8390: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
83a0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
83b0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
83c0: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
83d0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
83e0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
83f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
8400: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8410: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
8420: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
8430: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
8440: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
8450: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
8460: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
8470: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
8480: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
8490: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
84a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
84b0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
84c0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
84d0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
84e0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
84f0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
8500: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
8510: 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69 6e   it.  .*/.#defin
8520: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
8530: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
8540: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8550: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
8560: 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  LE      2.#defin
8570: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
8580: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
8590: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
85a0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
85b0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
85c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
85d0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
85e0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
85f0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8600: 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e  E       6.#defin
8610: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
8620: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
8630: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
8640: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
8650: 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a  TED     8.../*.*
8660: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
8670: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
8680: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
8690: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
86a0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
86b0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
86c0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
86d0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
86e0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
86f0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
8700: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
8710: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
8720: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
8730: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
8740: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
8750: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
8760: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
8770: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
8780: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
8790: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
87a0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
87b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
87c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
87d0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
87e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
87f0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
8800: 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
8810: 53 3a 20 56 46 53 20 56 46 53 65 73 0a 2a 2a 0a  S: VFS VFSes.**.
8820: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
8830: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
8840: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
8850: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
8860: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
8870: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
8880: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
8890: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
88a0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
88b0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
88c0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
88d0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
88e0: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54  system"..**.** T
88f0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
8900: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
8910: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
8920: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
8930: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
8940: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
8950: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
8960: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
8970: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
8980: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
8990: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
89a0: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
89b0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
89c0: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
89d0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
89e0: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
89f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
8a00: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
8a10: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
8a20: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
8a30: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
8a40: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
8a50: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
8a60: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
8a70: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
8a80: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
8a90: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
8aa0: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
8ab0: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
8ac0: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
8ad0: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
8ae0: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
8af0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
8b00: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
8b10: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
8b20: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
8b30: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
8b40: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
8b50: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
8b60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
8b70: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
8b80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
8b90: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
8ba0: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
8bb0: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
8bc0: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
8bd0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
8be0: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
8bf0: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
8c00: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
8c10: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
8c20: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
8c30: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
8c40: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
8c50: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
8c60: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
8c70: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
8c80: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
8c90: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8ca0: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
8cb0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
8cc0: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
8cd0: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
8ce0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
8cf0: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
8d00: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
8d10: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
8d20: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
8d30: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
8d40: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
8d50: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
8d60: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
8d70: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
8d80: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
8d90: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
8da0: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
8db0: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
8dc0: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
8dd0: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
8de0: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
8df0: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
8e00: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
8e10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
8e20: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
8e30: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
8e40: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8e50: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
8e60: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
8e70: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
8e80: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
8e90: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
8ea0: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
8eb0: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
8ec0: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
8ed0: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
8ee0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8ef0: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
8f00: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
8f10: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
8f20: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
8f30: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
8f40: 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 10 alphanumeri
8f50: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
8f60: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
8f70: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
8f80: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
8f90: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
8fa0: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
8fb0: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
8fc0: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
8fd0: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
8fe0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8ff0: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
9000: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
9010: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
9020: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
9030: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
9040: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
9050: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
9060: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
9070: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
9080: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
9090: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
90a0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
90b0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
90c0: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
90d0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
90e0: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
90f0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
9100: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9110: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
9120: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
9130: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
9140: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
9150: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
9160: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9170: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
9180: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9190: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
91a0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
91b0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
91c0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
91d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
91e0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
91f0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
9200: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
9210: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
9220: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
9230: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
9240: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
9250: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
9260: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
9270: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
9280: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
9290: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
92a0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
92b0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
92c0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
92d0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
92e0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
92f0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
9300: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
9310: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
9320: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
9330: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
9340: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
9350: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
9360: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
9370: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
9380: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9390: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
93a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
93b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
93c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
93d0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
93e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
93f0: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
9400: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9410: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
9420: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9430: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
9440: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9450: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
9460: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
9470: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
9480: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
9490: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
94a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
94b0: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
94c0: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
94d0: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
94e0: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
94f0: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
9500: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
9510: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
9520: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
9530: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
9540: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
9550: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
9560: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
9570: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
9580: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
9590: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
95a0: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
95b0: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
95c0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
95d0: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
95e0: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
95f0: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
9600: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
9610: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
9620: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
9630: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
9640: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
9650: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
9660: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
9670: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
9680: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
9690: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
96a0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
96b0: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
96c0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
96d0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
96e0: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
96f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
9700: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9710: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
9720: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
9730: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
9740: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
9750: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
9760: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
9770: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
9780: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
9790: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
97a0: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
97b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
97c0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
97d0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
97e0: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
97f0: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
9800: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
9810: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
9820: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
9830: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
9840: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
9850: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
9860: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
9870: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
9880: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
9890: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
98a0: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
98b0: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
98c0: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
98d0: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
98e0: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
98f0: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
9900: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
9910: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
9920: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
9930: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
9940: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
9950: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
9960: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
9970: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
9980: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
9990: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
99a0: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
99b0: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
99c0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
99d0: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
99e0: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
99f0: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
9a00: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
9a10: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
9a20: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
9a30: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9a40: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
9a50: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
9a60: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
9a70: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
9a80: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
9a90: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
9aa0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
9ab0: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
9ac0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
9ad0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
9ae0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
9af0: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
9b00: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
9b10: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
9b20: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
9b30: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
9b40: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
9b50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
9b60: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
9b70: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
9b80: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
9b90: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
9ba0: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
9bb0: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
9bc0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
9bd0: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
9be0: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
9bf0: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
9c00: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
9c10: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
9c20: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
9c30: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
9c40: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
9c50: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
9c60: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
9c70: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
9c80: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
9c90: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
9ca0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
9cb0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
9cc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9cd0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
9ce0: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
9cf0: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
9d00: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
9d10: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
9d20: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
9d30: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
9d40: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
9d50: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
9d60: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
9d70: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
9d80: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
9d90: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
9da0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
9db0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
9dc0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
9dd0: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
9de0: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
9df0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
9e00: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
9e10: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
9e20: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
9e30: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
9e40: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
9e50: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
9e60: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
9e70: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
9e80: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
9e90: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
9ea0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
9eb0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
9ec0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
9ed0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
9ee0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
9ef0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
9f00: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
9f10: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
9f20: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
9f30: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9f40: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
9f50: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
9f60: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
9f70: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
9f80: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
9f90: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
9fa0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
9fb0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
9fc0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
9fd0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
9fe0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
9ff0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
a000: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
a010: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
a020: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
a030: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
a040: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
a050: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
a060: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
a070: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
a080: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
a090: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
a0a0: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
a0b0: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
a0c0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
a0d0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
a0e0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
a0f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
a100: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
a110: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a120: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
a130: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
a140: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
a150: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
a160: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
a170: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
a180: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
a190: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
a1a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a1b0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
a1c0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
a1d0: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
a1e0: 70 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30  pled by 86400000
a1f0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
a200: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
a210: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
a220: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
a230: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
a240: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a250: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
a260: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
a270: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
a280: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
a290: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
a2a0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
a2b0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
a2c0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
a2d0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
a2e0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
a2f0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
a300: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
a310: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
a320: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
a330: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
a340: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
a350: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
a360: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
a370: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
a380: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
a390: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
a3a0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
a3b0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
a3c0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
a3d0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
a3e0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
a3f0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
a400: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
a410: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
a420: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
a430: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
a440: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
a450: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
a460: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
a470: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
a480: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
a490: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
a4a0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
a4b0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
a4c0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
a4d0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
a4e0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
a4f0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
a500: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
a510: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
a520: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
a530: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
a540: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
a550: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
a560: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
a570: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
a580: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
a590: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
a5a0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
a5b0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
a5c0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
a5d0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
a5e0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
a5f0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
a600: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
a610: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
a620: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
a630: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
a640: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
a650: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
a660: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
a670: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
a680: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
a690: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
a6a0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
a6b0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
a6c0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
a6d0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
a6e0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
a6f0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
a700: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
a710: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
a720: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
a730: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
a740: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
a750: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
a760: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
a770: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
a780: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
a790: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
a7a0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
a7b0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
a7c0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
a7d0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
a7e0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
a7f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
a800: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
a810: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
a820: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
a830: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
a840: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
a850: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
a860: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a870: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
a880: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
a890: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
a8a0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
a8b0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
a8c0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
a8d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
a8e0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
a8f0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
a900: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
a910: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
a920: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
a930: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
a940: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
a950: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
a960: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
a970: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
a980: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
a990: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
a9a0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
a9b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
a9c0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
a9d0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
a9e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
a9f0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
aa00: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
aa10: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
aa20: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
aa30: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
aa40: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
aa50: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
aa60: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
aa70: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
aa80: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
aa90: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
aaa0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
aab0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
aac0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
aad0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
aae0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
aaf0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
ab00: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
ab10: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
ab20: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
ab30: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
ab40: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ab50: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ab60: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
ab70: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ab80: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
ab90: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
aba0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
abb0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
abc0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
abd0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
abe0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
abf0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
ac00: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
ac10: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
ac20: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ac30: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
ac40: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ac50: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
ac60: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
ac70: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
ac80: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
ac90: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
aca0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
acb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
acc0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
acd0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
ace0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
acf0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
ad00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ad10: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ad20: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
ad30: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
ad40: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ad50: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ad60: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
ad70: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ad80: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ad90: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
ada0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
adb0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
adc0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
add0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
ade0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
adf0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
ae00: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
ae10: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
ae20: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
ae30: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ae40: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ae50: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
ae60: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
ae70: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
ae80: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
ae90: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
aea0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
aeb0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
aec0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
aed0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
aee0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
aef0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
af00: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
af10: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
af20: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
af30: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
af40: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
af50: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
af60: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
af70: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
af80: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
af90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
afa0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
afb0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
afc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
afd0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
afe0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
aff0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
b000: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
b010: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
b020: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
b030: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
b040: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
b050: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
b060: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b070: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
b080: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
b090: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
b0a0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
b0b0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
b0c0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
b0d0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
b0e0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
b0f0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
b100: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
b110: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
b120: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
b130: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
b140: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
b150: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
b160: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
b170: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
b180: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
b190: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
b1a0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
b1b0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
b1c0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
b1d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
b1e0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
b1f0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
b200: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
b210: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
b220: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
b230: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
b240: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b250: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
b260: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
b270: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
b280: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
b290: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
b2a0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
b2b0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
b2c0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
b2d0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
b2e0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
b2f0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
b300: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
b310: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
b320: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
b330: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
b340: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
b350: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
b360: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b370: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
b380: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
b390: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
b3a0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
b3b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
b3c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b3d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
b3e0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
b3f0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
b400: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
b410: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
b420: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
b430: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
b440: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
b450: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
b460: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
b470: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
b480: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
b490: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
b4a0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
b4b0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
b4c0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
b4d0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
b4e0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
b4f0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
b500: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
b510: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
b520: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
b530: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
b540: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
b550: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
b560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
b570: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
b580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b590: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
b5a0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
b5b0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
b5c0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
b5d0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
b5e0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
b5f0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
b600: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
b610: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
b620: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
b630: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
b640: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
b650: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
b660: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
b670: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
b680: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
b690: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
b6a0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
b6b0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
b6c0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
b6d0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
b6e0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
b6f0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
b700: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
b710: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
b720: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
b730: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
b740: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
b750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
b760: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
b770: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
b780: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
b790: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b7a0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
b7b0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
b7c0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
b7d0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
b7e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b7f0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
b800: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
b810: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
b820: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
b830: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
b840: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
b850: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
b860: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
b870: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
b880: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
b890: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
b8a0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
b8b0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
b8c0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
b8d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b8e0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
b8f0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
b900: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
b910: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b920: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
b930: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
b940: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
b950: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
b960: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
b970: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
b980: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
b990: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
b9a0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
b9b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b9c0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
b9d0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
b9e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b9f0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
ba00: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
ba10: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
ba20: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ba30: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
ba40: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ba50: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
ba60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ba70: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
ba80: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
ba90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
baa0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
bab0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
bac0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
bad0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
bae0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
baf0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
bb00: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
bb10: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
bb20: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
bb30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
bb40: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
bb50: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
bb60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
bb70: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
bb80: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
bb90: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
bba0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
bbb0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
bbc0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
bbd0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
bbe0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
bbf0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
bc00: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
bc10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bc20: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
bc30: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
bc40: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
bc50: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
bc60: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
bc70: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
bc80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bc90: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
bca0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
bcb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bcc0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
bcd0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
bce0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
bcf0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
bd00: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
bd10: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
bd20: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
bd30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
bd40: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
bd50: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
bd60: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
bd70: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
bd80: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
bd90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
bda0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
bdb0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
bdc0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
bdd0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
bde0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
bdf0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
be00: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
be10: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
be20: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
be30: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
be40: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
be50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
be60: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
be70: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
be80: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
be90: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
bea0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
beb0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
bec0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
bed0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
bee0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
bef0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
bf00: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
bf10: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
bf20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bf30: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
bf40: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
bf50: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
bf60: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
bf70: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
bf80: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
bf90: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
bfa0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
bfb0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
bfc0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
bfd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
bfe0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
bff0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
c000: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
c010: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
c020: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
c030: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c040: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
c050: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
c060: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
c070: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c080: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
c090: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
c0a0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
c0b0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
c0c0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
c0d0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
c0e0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
c0f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
c100: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
c110: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
c120: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
c130: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
c140: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
c150: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
c160: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
c170: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
c180: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
c190: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
c1a0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
c1b0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
c1c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
c1d0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
c1e0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
c1f0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
c200: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
c210: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
c220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
c230: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
c240: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
c250: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
c260: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
c270: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
c280: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
c290: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
c2a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
c2b0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
c2c0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
c2d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
c2e0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
c2f0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
c300: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
c310: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
c320: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
c330: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
c340: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
c350: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
c360: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
c370: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
c380: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
c390: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
c3a0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
c3b0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
c3c0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
c3d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
c3e0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
c3f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c400: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
c410: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c420: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
c430: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
c440: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
c450: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
c460: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
c470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
c480: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
c490: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
c4a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
c4b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
c4c0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
c4d0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
c4e0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
c4f0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
c500: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
c510: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c520: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
c530: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c540: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
c550: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
c560: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
c570: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
c580: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
c590: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
c5a0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
c5b0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
c5c0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
c5d0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
c5e0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
c5f0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
c600: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
c610: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
c620: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
c630: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
c640: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
c650: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
c660: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
c670: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
c680: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
c690: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
c6a0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
c6b0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
c6c0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
c6d0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
c6e0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
c6f0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
c700: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
c710: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
c720: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
c730: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c740: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
c750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
c760: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
c770: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
c780: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
c790: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
c7a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
c7b0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
c7c0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
c7d0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
c7e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
c7f0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
c800: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
c810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
c820: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
c830: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
c840: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
c850: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
c860: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
c870: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
c880: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
c890: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
c8a0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
c8b0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
c8c0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
c8d0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
c8e0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
c8f0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
c900: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
c910: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
c920: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
c930: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
c940: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c950: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
c960: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
c970: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
c980: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
c990: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
c9a0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
c9b0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
c9c0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
c9d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
c9e0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
c9f0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ca00: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ca10: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ca20: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ca30: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ca40: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ca50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ca60: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ca70: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ca80: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ca90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
caa0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
cab0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
cac0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
cad0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
cae0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
caf0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
cb00: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
cb10: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
cb20: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
cb30: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
cb40: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
cb50: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
cb60: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
cb70: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
cb80: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
cb90: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
cba0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
cbb0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
cbc0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
cbd0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
cbe0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
cbf0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
cc00: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
cc10: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
cc20: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
cc30: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
cc40: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
cc50: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
cc60: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
cc70: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
cc80: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
cc90: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
cca0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
ccb0: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
ccc0: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
ccd0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
cce0: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
ccf0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
cd00: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
cd10: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
cd20: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
cd30: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
cd40: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
cd50: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
cd60: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
cd70: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
cd80: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
cd90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cda0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
cdb0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cdc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
cdd0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
cde0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
cdf0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
ce00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ce10: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
ce20: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
ce30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ce40: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ce50: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ce60: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
ce70: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ce80: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
ce90: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
cea0: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
ceb0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
cec0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ced0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
cee0: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
cef0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
cf00: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
cf10: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
cf20: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
cf30: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
cf40: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
cf50: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
cf60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
cf70: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
cf80: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
cf90: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
cfa0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
cfb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
cfc0: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
cfd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
cfe0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
cff0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
d000: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
d010: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
d020: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
d030: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
d040: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
d050: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
d060: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d070: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
d080: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
d090: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
d0a0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
d0b0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
d0c0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
d0d0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
d0e0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
d0f0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
d100: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
d110: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
d120: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
d130: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d140: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
d150: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
d160: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
d170: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
d180: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
d190: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
d1a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d1b0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
d1c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d1d0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
d1e0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
d1f0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
d200: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
d210: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
d220: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
d230: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d240: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
d250: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
d260: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
d270: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
d280: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
d290: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
d2a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d2b0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
d2c0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
d2d0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
d2e0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
d2f0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
d300: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
d310: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
d320: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
d330: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
d340: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
d350: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
d360: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
d370: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
d380: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
d390: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
d3a0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
d3b0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
d3c0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
d3d0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
d3e0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
d3f0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
d400: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
d410: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
d420: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
d430: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
d440: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
d450: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
d460: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d470: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
d480: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
d490: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
d4a0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
d4b0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
d4c0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
d4d0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
d4e0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
d4f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
d500: 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d  lloc and xFree m
d510: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
d520: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
d530: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
d540: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
d550: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
d560: 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78  ibrary..** The x
d570: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d  Realloc method m
d580: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65  ust work like re
d590: 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65  alloc() from the
d5a0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
d5b0: 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ary.** with the 
d5c0: 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69  exception that i
d5d0: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
d5e0: 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f  ument to xReallo
d5f0: 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52  c is zero,.** xR
d600: 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61  ealloc must be a
d610: 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74   no-op - it must
d620: 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79   not perform any
d630: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a   allocation or.*
d640: 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  * deallocation. 
d650: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
d660: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
d670: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
d680: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
d690: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
d6a0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
d6b0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
d6c0: 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e  up..** And so in
d6d0: 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f   cases where xRo
d6e0: 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74  undup always ret
d6f0: 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20  urns a positive 
d700: 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c  number,.** xReal
d710: 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20  loc can perform 
d720: 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73  exactly as the s
d730: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
d740: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a  realloc() and.**
d750: 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d   still be in com
d760: 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69  pliance with thi
d770: 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e  s specification.
d780: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
d790: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
d7a0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
d7b0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d7c0: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
d7d0: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
d7e0: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
d7f0: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
d800: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
d810: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
d820: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
d830: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
d840: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
d850: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
d860: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
d870: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
d880: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
d890: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
d8a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
d8b0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
d8c0: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
d8d0: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
d8e0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
d8f0: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
d900: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
d910: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
d920: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
d930: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
d940: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
d950: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
d960: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
d970: 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
d980: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
d990: 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
d9a0: 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
d9b0: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
d9c0: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
d9d0: 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
d9e0: 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
d9f0: 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
da00: 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
da10: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
da20: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
da30: 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
da40: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
da50: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
da60: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
da70: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
da80: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
da90: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
daa0: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
dab0: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
dac0: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
dad0: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
dae0: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
daf0: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
db00: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
db10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
db20: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
db30: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
db40: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
db50: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
db60: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
db70: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
db80: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
db90: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
dba0: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
dbb0: 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
dbc0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
dbd0: 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
dbe0: 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
dbf0: 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
dc00: 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
dc10: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
dc20: 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
dc30: 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
dc40: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
dc50: 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
dc60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
dc70: 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
dc80: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
dc90: 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
dca0: 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
dcb0: 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
dcc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
dcd0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
dce0: 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
dcf0: 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
dd00: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
dd10: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
dd20: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dd30: 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
dd40: 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
dd50: 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
dd60: 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
dd70: 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
dd80: 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
dd90: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
dda0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ddb0: 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
ddc0: 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
ddd0: 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
dde0: 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
ddf0: 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
de00: 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
de10: 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
de20: 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
de30: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
de40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
de50: 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
de60: 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
de70: 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
de80: 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
de90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
dea0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
deb0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
dec0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
ded0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
dee0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
def0: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
df00: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
df10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
df20: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
df30: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
df40: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
df50: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
df60: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
df70: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
df80: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
df90: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
dfa0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
dfb0: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
dfc0: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
dfd0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
dfe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
dff0: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
e000: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
e010: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
e020: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
e030: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
e040: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
e050: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
e060: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
e070: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e080: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
e090: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
e0a0: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
e0b0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
e0c0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
e0d0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
e0e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e0f0: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
e100: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
e110: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
e120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e130: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
e140: 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
e150: 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
e160: 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
e170: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
e180: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
e190: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
e1a0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
e1b0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
e1c0: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
e1d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
e1e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e1f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
e200: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
e210: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
e220: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
e230: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
e240: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
e250: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
e260: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
e270: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
e280: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
e290: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
e2a0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
e2b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
e2c0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
e2d0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
e2e0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
e2f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
e300: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
e310: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
e320: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
e330: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
e340: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
e350: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
e360: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
e370: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
e380: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
e390: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e3a0: 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
e3b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
e3c0: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
e3d0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
e3e0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
e3f0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
e400: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
e410: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
e420: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
e430: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e440: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e450: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
e460: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
e470: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
e480: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
e490: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
e4a0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
e4b0: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
e4c0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
e4d0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
e4e0: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
e4f0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
e500: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
e510: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
e520: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
e530: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
e540: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e550: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
e560: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
e570: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
e580: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
e590: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
e5a0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
e5b0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
e5c0: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
e5d0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
e5e0: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
e5f0: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
e600: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
e610: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e620: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
e630: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e640: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e650: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e660: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e670: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e680: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e690: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e6a0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e6b0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e6c0: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e6d0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e6e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e6f0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e700: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e710: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e720: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e730: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e740: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e750: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e760: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e770: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e780: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e790: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e7a0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e7b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e7c0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e7d0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e7e0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e7f0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e800: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e810: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e820: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e830: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e840: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e850: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e860: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
e870: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e880: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
e890: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
e8a0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
e8b0: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
e8c0: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
e8d0: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
e8e0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e8f0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
e900: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e910: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
e920: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
e930: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
e940: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
e950: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
e960: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e970: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
e980: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e990: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
e9a0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
e9b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
e9c0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
e9d0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
e9e0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
e9f0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
ea00: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
ea10: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
ea20: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
ea30: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ea40: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
ea50: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ea60: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ea70: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ea80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ea90: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
eaa0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
eab0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
eac0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ead0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
eae0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
eaf0: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
eb00: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
eb10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
eb20: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
eb30: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
eb40: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
eb50: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
eb60: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
eb70: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
eb80: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
eb90: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
eba0: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
ebb0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
ebc0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
ebd0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
ebe0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
ebf0: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
ec00: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
ec10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ec20: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ec30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ec40: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ec50: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ec60: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ec70: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
ec80: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
ec90: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
eca0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
ecb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
ecc0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
ecd0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ece0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
ecf0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
ed00: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
ed10: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ed20: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
ed30: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
ed40: 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
ed50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
ed60: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
ed70: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ed80: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ed90: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
eda0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
edb0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
edc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
edd0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
ede0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
edf0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
ee00: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
ee10: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
ee20: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
ee30: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
ee40: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
ee50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ee60: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
ee70: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
ee80: 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
ee90: 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
eea0: 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
eeb0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
eec0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
eed0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
eee0: 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
eef0: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
ef00: 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
ef10: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
ef20: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
ef30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ef40: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
ef50: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
ef60: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
ef70: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
ef80: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
ef90: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
efa0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
efb0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
efc0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
efd0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
efe0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
eff0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
f000: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
f010: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
f020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f030: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
f040: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
f050: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
f060: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
f070: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
f080: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
f090: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
f0a0: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
f0b0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
f0c0: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
f0d0: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
f0e0: 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
f0f0: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
f100: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
f110: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
f120: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
f130: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
f140: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
f150: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
f160: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
f170: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
f180: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
f190: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
f1a0: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
f1b0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
f1c0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
f1d0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
f1e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f1f0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
f200: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
f210: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
f220: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
f230: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
f240: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
f250: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f260: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
f270: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f280: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
f290: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
f2a0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
f2b0: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
f2c0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f2d0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
f2e0: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
f2f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f300: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
f310: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
f320: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
f330: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
f340: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
f350: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
f360: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
f370: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
f380: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
f390: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
f3a0: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
f3b0: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f3c0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
f3d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f3e0: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
f3f0: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f400: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f410: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f420: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f430: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f440: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
f450: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
f460: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
f470: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
f480: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
f490: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
f4a0: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
f4b0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
f4c0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
f4d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
f4e0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
f4f0: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
f500: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
f510: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
f520: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
f530: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
f540: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
f550: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
f560: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f570: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
f580: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
f590: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
f5a0: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
f5b0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
f5c0: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
f5d0: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
f5e0: 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
f5f0: 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
f600: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
f610: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
f620: 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
f630: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
f640: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
f650: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f660: 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
f670: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
f680: 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
f690: 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
f6a0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
f6b0: 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
f6c0: 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
f6d0: 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
f6e0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
f6f0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
f700: 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
f710: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
f720: 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
f730: 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
f740: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
f750: 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
f760: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
f770: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
f780: 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
f790: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f7a0: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
f7b0: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
f7c0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
f7d0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
f7e0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
f7f0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
f800: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
f810: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
f820: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
f830: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
f840: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
f850: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
f860: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
f870: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
f880: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
f890: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f8a0: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
f8b0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
f8c0: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
f8d0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
f8e0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
f8f0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
f900: 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
f910: 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
f920: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
f930: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
f940: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
f950: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
f960: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
f970: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
f980: 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
f990: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
f9a0: 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
f9b0: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
f9c0: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
f9d0: 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
f9e0: 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
f9f0: 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
fa00: 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
fa10: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
fa20: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
fa30: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
fa40: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
fa50: 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
fa60: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
fa70: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
fa80: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
fa90: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
faa0: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
fab0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
fac0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
fad0: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
fae0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
faf0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
fb00: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
fb10: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
fb20: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
fb30: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
fb40: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
fb50: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
fb60: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
fb70: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
fb80: 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
fb90: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
fba0: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
fbb0: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
fbc0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
fbd0: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
fbe0: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
fbf0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
fc00: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
fc10: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
fc20: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
fc30: 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
fc40: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
fc50: 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
fc60: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
fc70: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
fc80: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
fc90: 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
fca0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
fcb0: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
fcc0: 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
fcd0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
fce0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
fcf0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
fd00: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
fd10: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
fd20: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
fd30: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
fd40: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
fd50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fd60: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
fd70: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
fd80: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
fd90: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
fda0: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
fdb0: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
fdc0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
fdd0: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
fde0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
fdf0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
fe00: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
fe10: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
fe20: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
fe30: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
fe40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
fe50: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
fe60: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
fe70: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
fe80: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
fe90: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
fea0: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
feb0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
fec0: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
fed0: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
fee0: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
fef0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
ff00: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
ff10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
ff20: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
ff30: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ff40: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ff50: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ff60: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ff70: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ff80: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ff90: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ffa0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ffb0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
ffc0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
ffd0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
ffe0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
fff0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
10000 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
10010 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
10020 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
10030 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
10040 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
10050 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
10060 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
10070 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
10080 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
10090 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
100a0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
100b0 64 20 61 74 20 32 5e 31 32 2e 20 52 65 61 73 6f  d at 2^12. Reaso
100c0 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
100d0 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
100e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
100f0 61 72 65 20 32 5e 35 20 74 68 72 6f 75 67 68 20  are 2^5 through 
10100 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  2^8.</dd>.**.** 
10110 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10120 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
10130 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
10140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10150 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10160 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10170 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10180 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10190 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
101a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
101b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
101c0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
101d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
101e0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
101f0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
10200 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10210 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
10220 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
10230 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
10240 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
10250 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
10260 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
10270 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10280 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10290 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
102a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
102b0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
102c0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
102d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
102e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
102f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10300 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10310 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10320 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
10330 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
10340 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
10350 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
10360 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
10370 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
10380 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10390 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
103a0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
103b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
103c0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
103d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
103e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
103f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10400 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
10410 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
10420 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10430 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10440 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10450 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10460 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10470 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10480 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10490 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
104a0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
104b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
104c0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
104d0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
104e0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
104f0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
10500 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
10510 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
10520 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
10530 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
10540 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10550 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10560 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
10570 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
10580 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
10590 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
105a0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
105b0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
105c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
105d0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
105e0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
105f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10600 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
10610 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10620 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
10630 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
10640 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
10650 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
10660 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
10670 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10680 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10690 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
106a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
106b0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
106c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
106d0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
106e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
106f0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
10700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10710 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
10720 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10730 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
10740 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
10750 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
10760 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
10770 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
10780 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
10790 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
107a0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
107b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
107c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
107d0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
107e0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
107f0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
10800 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
10810 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10820 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
10830 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
10840 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
10850 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
10860 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
10870 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
10880 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
10890 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
108a0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
108b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
108c0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
108d0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
108e0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
108f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10900 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
10910 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
10920 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10930 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
10940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10950 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  IG_PCACHE</dt>.*
10960 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10970 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10980 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10990 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
109a0 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
109b0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
109c0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
109d0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
109e0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
109f0 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
10a00 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
10a10 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
10a20 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
10a30 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
10a40 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
10a50 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
10a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
10a70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
10a90 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10aa0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
10ab0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10ac0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10ad0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10ae0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10af0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
10b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
10b10 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
10b20 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
10b30 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
10b40 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
10b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
10b60 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
10b70 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
10b80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
10b90 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
10ba0 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
10bb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
10bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
10bd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
10be0 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
10bf0 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
10c00 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
10c10 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
10c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
10c30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
10c40 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
10c50 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
10c60 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
10c70 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
10c80 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
10c90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
10ca0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
10cb0 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
10cc0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
10cd0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
10ce0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
10cf0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
10d00 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
10d10 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
10d20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
10d30 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
10d40 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
10d50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
10d60 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
10d70 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
10d80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
10d90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10da0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
10db0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
10dc0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
10dd0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
10de0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
10df0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
10e00 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
10e10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
10e20 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
10e30 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10e40 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
10e50 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
10e60 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
10e70 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
10e80 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
10e90 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
10ea0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
10eb0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
10ec0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
10ed0 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
10ee0 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
10ef0 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
10f00 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
10f10 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
10f20 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
10f30 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
10f40 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
10f50 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
10f60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
10f70 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
10f80 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
10f90 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
10fa0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
10fb0 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
10fc0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10fd0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
10fe0 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
10ff0 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
11000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11010 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
11020 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
11030 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
11040 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
11050 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
11060 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a  pe int. If non-z
11070 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49  ero, then.** URI
11080 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
11090 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
110a0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
110b0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  is zero, then UR
110c0 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73  I handling.** is
110d0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
110e0 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c  ed. If URI handl
110f0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
11100 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
11110 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
11120 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
11130 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
11140 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
11150 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
11160 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
11170 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
11180 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
11190 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
111a0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
111b0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
111c0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
111d0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
111e0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
111f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
11200 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
11210 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c   If it is global
11220 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
11230 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
11240 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
11250 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
11260 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
11270 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
11280 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
11290 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
112a0 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ned. By default,
112b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
112c0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
112d0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
112e0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
112f0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
11300 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
11310 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
11320 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
11330 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
11340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11350 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11360 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
11370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11380 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11390 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
113a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
113b0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
113c0 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
113d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
113e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
113f0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
11400 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
11410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11420 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11430 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
11440 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11450 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11460 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11470 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
11480 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
11490 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
114a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
114b0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
114c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
114d0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
114e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
114f0 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
11500 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
11510 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
11520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11530 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
11540 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
11550 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
11560 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
11570 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
11580 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11590 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
115a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
115b0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
115c0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
115d0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
115e0 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
115f0 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
11600 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
11610 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
11620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11630 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11640 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
11650 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
11660 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
11670 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
11680 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
11690 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
116a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
116b0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
116c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
116d0 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
116e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
116f0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
11700 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
11710 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
11720 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
11730 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
11740 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  /* int */../*.**
11750 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
11760 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
11770 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11780 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
11790 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
117a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
117b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
117c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
117d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
117e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
117f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11800 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11810 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
11820 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11830 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11840 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
11850 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
11860 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11870 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11880 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11890 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
118a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
118b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
118c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
118d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
118e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
118f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
11900 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
11910 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
11920 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
11930 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
11940 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
11950 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
11960 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
11970 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
11980 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11990 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
119a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
119b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
119c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
119d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
119e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
119f0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
11a00 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
11a10 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
11a20 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
11a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
11a40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
11a50 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
11a60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
11a70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
11a80 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
11a90 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11aa0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11ab0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
11ac0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
11ad0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
11ae0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
11af0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
11b00 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
11b10 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
11b20 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
11b30 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
11b40 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
11b50 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
11b60 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
11b70 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
11b80 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
11b90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
11ba0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11bb0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11bc0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11bd0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
11be0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
11bf0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
11c00 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
11c10 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
11c20 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
11c30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11c40 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
11c50 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
11c60 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
11c70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
11c80 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
11c90 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
11ca0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
11cb0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
11cc0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
11cd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11ce0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
11cf0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11d00 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
11d10 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
11d20 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
11d30 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
11d40 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
11d50 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
11d60 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
11d70 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
11d80 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
11d90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
11da0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
11db0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
11dc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
11dd0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
11de0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
11df0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
11e00 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
11e10 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
11e20 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
11e30 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
11e40 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
11e50 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
11e60 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
11e70 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
11e80 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
11e90 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
11ea0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
11eb0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
11ec0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
11ed0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
11ee0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
11ef0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
11f00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
11f10 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
11f20 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
11f30 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
11f40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11f50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
11f60 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
11f70 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
11f80 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
11f90 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
11fa0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
11fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
11fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
11fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
11fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
11ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
12000 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
12010 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
12020 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
12030 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
12040 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
12050 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
12060 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
12070 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
12080 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
12090 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
120a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
120b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
120c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
120d0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
120e0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
120f0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
12100 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
12110 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12120 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
12130 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
12140 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
12150 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
12160 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
12170 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
12180 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
12190 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
121a0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
121b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
121c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
121d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
121e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
121f0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
12200 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
12210 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
12220 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
12230 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12240 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
12250 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
12260 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
12270 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
12280 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
12290 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
122a0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
122b0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
122c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
122d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
122e0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
122f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
12300 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
12310 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
12320 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
12330 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
12340 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
12350 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
12360 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
12370 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
12380 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
12390 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
123a0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
123b0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
123c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
123d0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
123e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
123f0 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
12400 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
12410 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
12420 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12430 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
12440 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
12450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12460 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
12470 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
12480 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
12490 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
124a0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
124b0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
124c0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
124d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
124e0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
124f0 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
12500 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12510 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
12520 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
12530 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
12540 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
12550 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
12560 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
12570 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
12580 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
12590 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
125a0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
125b0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
125c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
125d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
125e0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
125f0 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
12600 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
12610 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
12620 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
12630 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
12640 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
12650 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
12660 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
12670 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
12680 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
12690 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
126a0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
126b0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
126c0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
126d0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
126e0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
126f0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
12700 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
12710 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
12720 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
12730 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
12740 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
12750 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
12760 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
12770 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
12780 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
12790 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
127a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
127b0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
127c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
127d0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
127e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
127f0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
12800 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12810 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
12820 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
12830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
12840 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
12850 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
12860 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
12870 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
12880 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
12890 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
128a0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
128b0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
128c0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
128d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
128e0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
128f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
12900 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
12910 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
12920 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
12930 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
12940 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
12950 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
12960 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
12970 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
12980 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
12990 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
129a0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
129b0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
129c0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
129d0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
129e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
129f0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
12a00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
12a10 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
12a20 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
12a30 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
12a40 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
12a50 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
12a60 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
12a70 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
12a80 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
12a90 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
12aa0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
12ab0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
12ac0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
12ad0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
12ae0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
12af0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
12b00 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
12b10 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
12b20 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
12b30 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
12b40 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
12b50 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
12b60 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
12b70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
12b80 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
12b90 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
12ba0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
12bb0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
12bc0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
12bd0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
12be0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
12bf0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
12c00 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
12c10 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
12c20 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
12c30 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
12c40 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
12c50 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
12c60 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
12c70 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
12c80 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
12c90 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
12ca0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
12cb0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
12cc0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
12cd0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
12ce0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
12cf0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
12d00 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
12d10 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
12d20 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
12d30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
12d40 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
12d50 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
12d60 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
12d70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
12d80 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
12d90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
12da0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
12db0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
12dc0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
12dd0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
12de0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
12df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
12e00 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
12e10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
12e20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
12e30 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
12e40 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
12e50 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
12e60 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12e70 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
12e80 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
12e90 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
12ea0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
12eb0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
12ec0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
12ed0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
12ee0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
12ef0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
12f00 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
12f10 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
12f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12f30 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
12f40 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
12f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
12f60 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
12f70 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
12f80 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
12f90 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
12fa0 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
12fb0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
12fc0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
12fd0 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
12fe0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
12ff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13000 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
13010 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13020 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
13030 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
13040 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
13050 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
13060 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
13070 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
13080 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
13090 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
130a0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
130b0 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
130c0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
130d0 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
130e0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
130f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
13100 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
13110 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
13120 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
13130 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
13140 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
13150 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
13160 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
13170 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
13180 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
13190 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
131a0 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
131b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
131c0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
131d0 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
131e0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
131f0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
13200 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
13210 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
13220 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
13230 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
13240 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
13250 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
13260 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
13270 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
13280 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
13290 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
132a0 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
132b0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
132c0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
132d0 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
132e0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
132f0 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
13300 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
13310 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
13320 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
13330 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
13340 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
13350 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
13360 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
13370 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
13380 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
13390 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
133a0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
133b0 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
133c0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
133d0 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
133e0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
133f0 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
13400 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
13410 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
13420 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
13430 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
13440 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
13450 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
13460 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
13470 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
13480 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
13490 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
134a0 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
134b0 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
134c0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
134d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
134e0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
134f0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
13500 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
13510 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
13520 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
13540 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
13550 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
13560 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
13570 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
13580 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
13590 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
135a0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
135b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
135c0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
135d0 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
135e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
135f0 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
13600 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
13610 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
13620 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
13630 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
13640 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
13650 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
13660 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
13670 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
13680 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
13690 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
136a0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
136b0 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
136c0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
136d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
136e0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
136f0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
13700 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
13710 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13720 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
13730 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
13740 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
13750 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
13760 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
13770 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
13780 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
13790 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
137a0 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
137b0 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
137c0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
137d0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
137e0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
137f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
13800 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
13810 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
13820 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
13830 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
13840 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
13850 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
13860 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
13870 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
13880 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
13890 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
138a0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
138b0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
138c0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
138d0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
138e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
138f0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
13900 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
13910 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
13920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13930 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
13940 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
13950 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
13960 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
13970 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
13980 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
13990 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
139a0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
139b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
139c0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
139d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
139e0 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
139f0 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
13a00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
13a10 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
13a20 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
13a30 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
13a40 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
13a50 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
13a60 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
13a70 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
13a80 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
13a90 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
13aa0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
13ab0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
13ac0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
13ad0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
13ae0 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
13af0 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
13b00 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
13b10 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
13b20 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
13b30 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
13b40 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
13b50 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
13b60 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
13b70 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
13b80 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
13b90 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
13ba0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
13bb0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
13bc0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
13bd0 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
13be0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13bf0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
13c00 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
13c10 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
13c20 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
13c30 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
13c40 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
13c50 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
13c60 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
13c70 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
13c80 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
13c90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
13ca0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
13cb0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
13cc0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
13cd0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
13ce0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
13cf0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
13d00 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
13d10 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
13d20 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
13d30 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
13d40 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
13d50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13d60 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
13d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13d80 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
13d90 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
13da0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
13db0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
13dc0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
13dd0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
13de0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13df0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
13e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
13e10 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
13e20 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
13e30 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
13e40 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
13e50 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
13e60 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
13e70 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
13e80 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
13e90 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
13ea0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
13eb0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
13ec0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
13ed0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
13ee0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
13ef0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
13f00 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
13f10 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
13f20 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
13f30 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
13f40 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
13f50 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
13f60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
13f70 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
13f80 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
13f90 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
13fa0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
13fb0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
13fc0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
13fd0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
13fe0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
13ff0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
14000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14010 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
14020 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
14030 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
14040 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
14050 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
14060 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
14070 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
14080 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
14090 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
140a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
140b0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
140c0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
140d0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
140e0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
140f0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
14100 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
14110 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
14120 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
14130 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
14140 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
14150 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
14160 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
14170 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
14180 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
14190 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
141a0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
141b0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
141c0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
141d0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
141e0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
141f0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
14200 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
14210 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
14220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
14230 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
14240 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
14250 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
14260 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
14270 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
14280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14290 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
142a0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
142b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
142c0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
142d0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
142e0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
142f0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
14300 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
14310 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
14320 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
14330 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
14340 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
14350 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
14360 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14370 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
14380 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
14390 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
143a0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
143b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
143c0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
143d0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
143e0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
143f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
14400 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
14410 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14420 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
14430 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
14440 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
14450 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
14460 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
14470 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
14480 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
14490 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
144a0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
144b0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
144c0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
144d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
144e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
144f0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
14500 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
14510 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14520 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
14530 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
14540 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
14550 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
14560 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
14570 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
14580 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
14590 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
145a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
145b0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
145c0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
145d0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
145e0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
145f0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
14600 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
14610 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
14620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
14630 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
14640 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
14650 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
14660 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
14670 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
14680 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
14690 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
146a0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
146b0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
146c0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
146d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
146e0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
146f0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
14700 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
14710 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
14720 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
14730 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
14740 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
14750 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
14760 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
14770 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
14780 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
14790 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
147a0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
147b0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
147c0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
147d0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
147e0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
147f0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
14800 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
14810 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
14820 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
14830 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
14840 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
14850 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
14860 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
14870 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
14880 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
14890 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
148a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
148b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
148c0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
148d0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
148e0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
148f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
14900 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
14910 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
14920 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
14930 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
14940 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
14950 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
14960 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
14970 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
14980 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
14990 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
149a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
149b0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
149c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
149d0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
149e0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
149f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
14a00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
14a10 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
14a20 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
14a30 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
14a40 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
14a50 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
14a60 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
14a70 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
14a80 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
14a90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
14aa0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
14ab0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
14ac0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
14ad0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
14ae0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
14af0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
14b00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
14b10 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
14b20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14b30 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
14b40 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
14b50 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
14b60 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
14b70 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
14b80 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
14b90 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
14ba0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
14bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
14bc0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
14bd0 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
14be0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
14bf0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
14c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14c10 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
14c20 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
14c30 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
14c40 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
14c50 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
14c60 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
14c70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
14c80 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
14c90 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
14ca0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
14cb0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
14cc0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
14cd0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
14ce0 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
14cf0 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
14d00 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
14d10 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
14d20 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
14d30 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
14d40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
14d50 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
14d60 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
14d70 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
14d80 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
14d90 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
14da0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
14db0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
14dc0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
14dd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
14de0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14df0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14e00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
14e10 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
14e20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
14e30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
14e40 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
14e50 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
14e60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14e70 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
14e80 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
14e90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14ea0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
14eb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
14ec0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
14ed0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
14ee0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14ef0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
14f00 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
14f10 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
14f20 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
14f30 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
14f40 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
14f50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
14f60 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
14f70 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
14f80 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
14f90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
14fa0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
14fb0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
14fc0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
14fd0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
14fe0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
14ff0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
15000 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
15010 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
15020 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
15030 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
15040 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
15050 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
15060 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
15070 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
15080 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
15090 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
150a0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
150b0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
150c0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
150d0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
150e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
150f0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
15100 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15110 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
15120 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
15130 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
15140 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
15150 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
15160 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
15170 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
15180 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
15190 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
151a0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
151b0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
151c0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
151d0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
151e0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
151f0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
15200 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
15210 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
15220 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
15230 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
15240 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
15250 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15260 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
15270 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
15280 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
15290 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
152a0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
152b0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
152c0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
152d0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
152e0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
152f0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
15300 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
15310 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
15320 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
15330 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
15340 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
15350 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
15360 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
15370 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
15380 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
15390 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
153a0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
153b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
153c0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
153d0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
153e0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
153f0 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
15400 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
15410 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15420 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
15430 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
15440 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
15450 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
15460 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
15470 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
15480 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
15490 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
154a0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
154b0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
154c0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
154d0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
154e0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
154f0 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
15500 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
15510 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
15520 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
15530 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
15540 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
15550 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
15560 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
15570 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
15580 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
15590 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
155a0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
155b0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
155c0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
155d0 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
155e0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
155f0 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
15600 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
15610 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
15620 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
15630 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
15640 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15650 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
15660 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
15670 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
15680 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
15690 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
156a0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
156b0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
156c0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
156d0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
156e0 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
156f0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
15700 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
15710 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
15720 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
15730 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
15740 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
15750 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
15760 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
15770 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
15780 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
15790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
157a0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
157b0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
157c0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
157d0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
157e0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
157f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
15800 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
15810 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
15820 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
15830 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
15840 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
15850 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
15860 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
15870 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
15880 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15890 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
158a0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
158b0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
158c0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
158d0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
158e0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
158f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
15900 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
15910 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15920 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
15930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
15940 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
15950 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
15960 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
15970 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
15980 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
15990 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
159a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
159b0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
159c0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
159d0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
159e0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
159f0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
15a00 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
15a10 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
15a20 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
15a30 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
15a40 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
15a50 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
15a60 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
15a70 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
15a80 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
15a90 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
15aa0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
15ab0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
15ac0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
15ad0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
15ae0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
15af0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
15b00 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
15b10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
15b20 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
15b30 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
15b40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
15b50 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
15b60 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
15b70 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
15b80 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
15b90 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
15ba0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
15bb0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
15bc0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
15bd0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
15be0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
15bf0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
15c00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15c10 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
15c20 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
15c30 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
15c40 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
15c50 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
15c60 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
15c70 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
15c80 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
15c90 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
15ca0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
15cb0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
15cc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
15cd0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
15ce0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
15cf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
15d00 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
15d10 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
15d20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
15d30 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
15d40 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
15d50 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
15d60 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
15d70 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
15d80 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
15d90 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
15da0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
15db0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
15dc0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
15dd0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
15de0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
15df0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
15e00 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
15e10 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
15e20 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
15e30 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
15e40 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
15e50 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
15e60 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
15e70 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
15e80 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
15e90 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
15ea0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
15eb0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
15ec0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
15ed0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
15ee0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
15ef0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
15f00 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
15f10 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
15f20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
15f30 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
15f40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
15f50 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
15f60 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
15f70 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
15f80 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
15f90 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
15fa0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
15fb0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
15fc0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
15fd0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
15fe0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
15ff0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
16000 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
16010 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
16020 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
16030 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
16040 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
16050 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
16060 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
16070 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
16080 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
16090 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
160a0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
160b0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
160c0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
160d0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
160e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
160f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
16100 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
16110 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
16120 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
16130 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
16140 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
16150 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
16160 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
16170 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
16180 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
16190 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
161a0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
161b0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
161c0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
161d0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
161e0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
161f0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16200 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
16210 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
16220 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
16230 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16240 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
16250 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
16260 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
16270 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16280 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
16290 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
162a0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
162b0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
162c0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
162d0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
162e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
162f0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
16300 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
16310 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
16320 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
16330 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
16340 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
16350 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
16360 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
16370 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
16380 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
16390 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
163a0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
163b0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
163c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
163d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
163e0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
163f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16400 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
16410 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
16420 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
16430 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
16440 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16450 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
16460 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16470 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
16480 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16490 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
164a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
164b0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
164c0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
164d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
164e0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
164f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
16500 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
16510 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16520 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
16530 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
16540 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
16550 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
16560 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
16570 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16580 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
16590 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
165a0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
165b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
165c0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
165d0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
165e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
165f0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
16600 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
16610 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
16620 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
16630 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
16640 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
16650 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
16660 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
16670 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
16680 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
16690 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
166a0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
166b0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
166c0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
166d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
166e0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
166f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16700 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
16710 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
16720 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
16730 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
16740 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
16750 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
16760 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
16770 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
16780 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
16790 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
167a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
167b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
167c0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
167d0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
167e0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
167f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
16800 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
16810 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
16820 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
16830 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
16840 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
16850 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
16860 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
16870 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
16880 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
16890 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
168a0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
168b0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
168c0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
168d0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
168e0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
168f0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
16900 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
16910 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
16920 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
16930 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
16940 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
16950 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
16960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
16970 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
16980 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
16990 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
169a0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
169b0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
169c0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
169d0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
169e0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
169f0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
16a00 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
16a10 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
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 72 6f 77 73 20 77 72 69   result rows wri
16a40 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
16a50 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
16a60 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
16a70 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
16a80 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16a90 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
16aa0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
16ab0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
16ac0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
16ad0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
16ae0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
16af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16b00 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
16b10 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
16b20 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16b30 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
16b40 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
16b50 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
16b60 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
16b70 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
16b80 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
16b90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16ba0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
16bb0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
16bc0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
16bd0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
16be0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
16bf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
16c00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16c10 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
16c20 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
16c30 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
16c40 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
16c50 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
16c60 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
16c70 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
16c80 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
16c90 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
16ca0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
16cb0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
16cc0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
16cd0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
16ce0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
16cf0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
16d00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
16d10 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
16d20 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
16d30 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
16d40 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
16d50 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
16d60 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
16d70 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
16d80 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
16d90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
16da0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
16db0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
16dc0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
16dd0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
16de0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
16df0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
16e00 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
16e10 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
16e20 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
16e30 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
16e40 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
16e50 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
16e60 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
16e70 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
16e80 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
16e90 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
16ea0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
16eb0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
16ec0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
16ed0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
16ee0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
16ef0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
16f00 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
16f10 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
16f20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
16f30 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
16f40 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
16f50 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
16f60 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
16f70 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
16f80 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
16f90 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
16fa0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
16fb0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
16fc0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
16fd0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
16fe0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
16ff0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
17000 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
17010 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
17020 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
17030 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
17040 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
17050 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
17060 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
17070 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
17080 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
17090 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
170a0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
170b0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
170c0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
170d0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
170e0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
170f0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
17100 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
17110 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
17120 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
17130 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
17140 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
17150 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
17160 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
17170 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
17180 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
17190 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
171a0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
171b0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
171c0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
171d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
171e0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
171f0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
17200 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
17210 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
17220 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
17230 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
17240 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
17250 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
17260 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
17270 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
17280 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
17290 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
172a0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
172b0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
172c0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
172d0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
172e0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
172f0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
17300 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
17310 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
17320 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
17330 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
17340 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
17350 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
17360 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
17370 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
17380 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
17390 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
173a0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
173b0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
173c0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
173d0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
173e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
173f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17400 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
17410 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
17420 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17430 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
17440 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
17450 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
17460 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
17470 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17480 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
17490 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
174a0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
174b0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
174c0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
174d0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
174e0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
174f0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17500 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
17510 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17520 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
17530 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
17540 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
17550 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
17560 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
17570 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
17580 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
17590 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
175a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
175b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
175c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
175d0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
175e0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
175f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17600 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
17610 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
17620 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
17630 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
17640 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
17650 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
17660 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
17670 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17680 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
17690 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
176a0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
176b0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
176c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
176d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
176e0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
176f0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
17700 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
17710 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
17720 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
17730 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
17740 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
17750 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
17760 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
17770 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
17780 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
17790 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
177a0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
177b0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
177c0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
177d0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
177e0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
177f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
17800 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
17810 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
17820 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
17830 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
17840 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
17850 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
17860 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
17870 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
17880 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
17890 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
178a0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
178b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
178c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
178d0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
178e0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
178f0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
17900 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
17910 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
17920 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
17930 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
17940 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
17950 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
17960 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
17970 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
17980 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
17990 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
179a0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
179b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
179c0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
179d0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
179e0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
179f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
17a00 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
17a10 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
17a20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
17a30 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
17a40 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
17a50 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
17a60 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
17a70 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
17a80 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
17a90 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
17aa0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
17ab0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
17ac0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
17ad0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
17ae0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
17af0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17b00 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
17b10 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
17b20 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
17b30 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
17b40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17b50 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
17b60 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
17b70 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
17b80 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
17b90 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
17ba0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
17bb0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
17bc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
17bd0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
17be0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
17bf0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
17c00 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
17c10 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
17c20 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
17c30 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
17c40 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
17c50 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
17c60 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
17c70 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
17c80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17c90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
17ca0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
17cb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
17cc0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
17cd0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
17ce0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
17cf0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
17d00 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
17d10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
17d20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
17d30 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
17d40 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
17d50 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
17d60 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
17d70 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
17d80 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
17d90 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
17da0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
17db0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
17dc0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
17dd0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
17de0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
17df0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
17e00 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
17e10 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
17e20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
17e30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
17e40 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
17e50 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
17e60 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
17e70 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
17e80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
17e90 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
17ea0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
17eb0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
17ec0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
17ed0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
17ee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
17ef0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
17f00 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
17f10 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
17f20 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
17f30 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
17f40 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
17f50 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
17f60 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
17f70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
17f80 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
17f90 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
17fa0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
17fb0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
17fc0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
17fd0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
17fe0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
17ff0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
18000 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
18010 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
18020 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
18030 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
18040 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
18050 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
18060 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18070 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
18080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
18090 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
180a0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
180b0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
180c0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
180d0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
180e0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
180f0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18100 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
18110 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
18120 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
18130 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18140 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
18150 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18160 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18170 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
18180 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
18190 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
181a0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
181b0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
181c0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
181d0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
181e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
181f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18200 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
18210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
18220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18230 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
18240 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
18250 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
18260 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
18270 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
18280 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
18290 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
182a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
182b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
182c0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
182d0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
182e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
182f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
18300 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
18310 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
18320 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
18330 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
18340 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
18350 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
18360 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18370 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
18380 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
18390 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
183a0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
183b0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
183c0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
183d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
183e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
183f0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
18400 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
18410 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
18420 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
18430 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
18440 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18450 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
18460 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
18470 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
18480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
18490 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
184a0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
184b0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
184c0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
184d0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
184e0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
184f0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
18500 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
18510 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
18520 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
18530 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
18540 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
18550 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
18560 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
18570 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
18580 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
18590 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
185a0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
185b0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
185c0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
185d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
185e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
185f0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
18600 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
18610 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
18620 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
18630 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
18640 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
18650 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
18660 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
18670 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
18680 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
18690 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
186a0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
186b0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
186c0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
186d0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
186e0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
186f0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
18700 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
18710 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
18720 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
18730 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
18740 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
18750 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
18760 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
18770 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
18780 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
18790 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
187a0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
187b0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
187c0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
187d0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
187e0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
187f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
18800 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18810 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
18820 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
18830 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
18840 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
18850 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
18860 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
18870 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
18880 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
18890 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
188a0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
188b0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
188c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
188d0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
188e0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
188f0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
18900 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
18910 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
18920 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
18930 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
18940 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18950 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
18960 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
18970 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
18980 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
18990 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
189a0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
189b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
189c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
189d0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
189e0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
189f0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
18a00 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
18a10 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
18a20 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
18a30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
18a40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18a50 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
18a60 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
18a70 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
18a80 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
18a90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18aa0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
18ab0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
18ac0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
18ad0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
18ae0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
18af0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
18b00 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
18b10 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
18b20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
18b30 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
18b40 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18b50 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
18b60 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
18b70 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
18b80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
18b90 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
18ba0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
18bb0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
18bc0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
18bd0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
18be0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18bf0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
18c00 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18c10 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
18c20 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
18c30 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
18c40 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
18c50 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
18c60 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
18c70 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
18c80 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
18c90 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
18ca0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
18cb0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
18cc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
18cd0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
18ce0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
18cf0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
18d00 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
18d10 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
18d20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18d30 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
18d40 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
18d50 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [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 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
18d80 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
18d90 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
18da0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
18db0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
18dc0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
18dd0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
18de0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
18df0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
18e00 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
18e10 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
18e20 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
18e30 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
18e40 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
18e50 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
18e60 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
18e70 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
18e80 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
18e90 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
18ea0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
18eb0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
18ec0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
18ed0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
18ee0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
18ef0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
18f00 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
18f10 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
18f20 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
18f30 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
18f40 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
18f50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
18f60 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
18f70 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
18f80 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
18f90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
18fa0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
18fb0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
18fc0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
18fd0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
18fe0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
18ff0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
19000 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
19010 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
19020 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
19030 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
19040 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
19050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
19060 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
19070 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
19080 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
19090 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
190a0 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
190b0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
190c0 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
190d0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
190e0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
190f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
19100 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
19110 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
19120 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
19130 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
19140 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
19150 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
19160 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
19170 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
19180 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
19190 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
191a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
191b0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
191c0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
191d0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
191e0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
191f0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
19200 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
19210 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
19220 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19230 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
19240 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19250 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
19260 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
19270 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
19280 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
19290 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
192a0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
192b0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
192c0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
192d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
192e0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
192f0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
19300 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
19310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19320 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
19330 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19340 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
19350 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
19360 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
19370 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
19380 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
19390 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
193a0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
193b0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
193c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
193d0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
193e0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
193f0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
19400 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
19410 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
19420 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19430 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
19440 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
19450 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
19460 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
19470 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
19480 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
19490 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
194a0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
194b0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
194c0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
194d0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
194e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
194f0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
19500 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
19510 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
19520 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19530 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
19540 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
19550 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
19560 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
19570 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
19580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
19590 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
195a0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
195b0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
195c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
195d0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
195e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
195f0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
19600 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19610 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
19620 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
19630 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
19640 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
19650 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
19660 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
19670 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
19680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19690 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
196a0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
196b0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
196c0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
196d0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
196e0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
196f0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
19700 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
19710 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
19720 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19730 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19740 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
19750 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
19760 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
19770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19780 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
19790 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
197a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
197b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
197c0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
197d0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
197e0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
197f0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
19800 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
19810 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
19820 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
19830 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
19840 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
19850 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
19860 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
19870 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
19880 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
19890 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
198a0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
198b0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
198c0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
198d0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
198e0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
198f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19900 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
19910 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
19920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
19930 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
19940 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
19950 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
19960 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
19970 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
19980 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
19990 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
199a0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
199b0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
199c0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
199d0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
199e0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
199f0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
19a00 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
19a10 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
19a20 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
19a30 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
19a40 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
19a50 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
19a60 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
19a70 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
19a80 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
19a90 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
19aa0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
19ab0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
19ac0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
19ad0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
19ae0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
19af0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
19b00 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
19b10 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
19b20 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
19b30 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
19b40 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
19b50 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
19b60 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
19b70 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
19b80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19b90 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
19ba0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
19bb0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
19bc0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
19bd0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
19be0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
19bf0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
19c00 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
19c10 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
19c20 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
19c30 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
19c40 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
19c50 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
19c60 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
19c70 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
19c80 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
19c90 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
19ca0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
19cb0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
19cc0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
19cd0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
19ce0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
19cf0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
19d00 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
19d10 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
19d20 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
19d30 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
19d40 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
19d50 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
19d60 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
19d70 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
19d80 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
19d90 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
19da0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
19db0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
19dc0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
19dd0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
19de0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
19df0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
19e00 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
19e10 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
19e20 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
19e30 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
19e40 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
19e50 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
19e60 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
19e70 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
19e80 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
19e90 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
19ea0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
19eb0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
19ec0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
19ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19ee0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
19ef0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
19f00 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
19f10 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
19f20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
19f30 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
19f40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
19f50 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
19f60 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
19f70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
19f80 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
19f90 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
19fa0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19fb0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
19fc0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
19fd0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
19fe0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19ff0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a000 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1a010 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1a020 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1a030 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a040 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1a050 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1a060 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1a070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1a080 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1a090 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1a0a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1a0b0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1a0c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a0d0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1a0e0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1a0f0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1a100 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1a110 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1a120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1a130 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1a140 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1a150 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1a160 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1a170 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1a180 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1a190 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1a1a0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1a1b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1a1c0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1a1d0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1a1e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a1f0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1a200 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1a210 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1a220 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1a230 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1a240 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1a250 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1a260 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1a270 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a280 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1a290 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1a2a0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1a2b0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1a2c0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1a2d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a2e0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1a2f0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1a300 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1a310 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a320 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1a330 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1a340 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1a350 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1a360 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1a370 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1a380 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1a390 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1a3a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1a3b0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1a3c0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1a3d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a3e0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1a3f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1a400 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1a410 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1a420 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1a430 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1a440 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1a450 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1a460 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1a470 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1a480 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1a490 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a4a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1a4b0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1a4c0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1a4d0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1a4e0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1a4f0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1a500 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1a510 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1a520 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1a530 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1a540 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1a550 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1a560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1a570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a580 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1a590 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1a5a0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1a5b0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1a5c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1a5d0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1a5e0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1a5f0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1a600 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1a610 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1a620 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1a630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1a640 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a650 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1a660 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1a670 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1a680 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1a690 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1a6a0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1a6b0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1a6c0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1a6d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1a6e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1a6f0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1a700 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1a710 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1a720 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1a730 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1a740 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1a750 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1a760 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a770 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1a780 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1a790 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1a7a0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1a7b0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1a7c0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1a7d0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1a7e0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1a7f0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1a800 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1a810 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1a820 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1a830 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1a840 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1a850 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1a860 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1a870 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1a880 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1a890 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1a8a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a8b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1a8c0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1a8d0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1a8e0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1a8f0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1a900 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a910 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a920 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1a930 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1a940 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1a950 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1a960 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1a970 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1a980 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1a990 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1a9a0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1a9b0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1a9c0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1a9d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a9e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a9f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1aa00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1aa10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1aa20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1aa30 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1aa40 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1aa50 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1aa60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1aa70 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1aa80 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1aa90 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1aaa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1aab0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aac0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1aad0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1aae0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1aaf0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ab00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ab10 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ab20 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1ab30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ab40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ab50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ab60 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ab70 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1ab80 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1ab90 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1aba0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1abb0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1abc0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1abd0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1abe0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1abf0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ac00 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1ac10 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1ac20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1ac30 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ac40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ac50 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1ac60 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1ac70 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1ac80 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ac90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1aca0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1acb0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1acc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1acd0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ace0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1acf0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1ad00 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1ad10 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1ad20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ad30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ad40 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1ad50 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1ad60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ad70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ad80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ad90 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1ada0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1adb0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1adc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1add0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ade0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1adf0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1ae00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ae10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ae20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ae30 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1ae40 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1ae50 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1ae60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ae70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ae80 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1ae90 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1aea0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1aeb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1aec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1aed0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1aee0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1aef0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1af00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1af20 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1af30 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1af40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1af50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1af70 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1af80 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1af90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1afa0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1afb0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1afc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1afd0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1afe0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1aff0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1b000 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1b010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1b020 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b030 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b040 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b050 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1b060 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1b070 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1b080 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b090 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b0a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1b0b0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1b0c0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1b0d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b0e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b0f0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1b100 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1b110 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b120 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1b130 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b140 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1b150 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1b160 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1b170 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b180 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b190 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1b1a0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1b1b0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1b1c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b1d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b1e0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1b1f0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1b200 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1b210 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b230 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1b240 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1b250 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1b260 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b280 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1b290 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1b2a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b2b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b2c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2d0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1b2e0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1b2f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1b300 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1b310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b320 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1b330 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1b340 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1b350 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1b360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1b370 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1b380 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1b390 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1b3a0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1b3b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1b3c0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1b3d0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1b3e0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1b3f0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1b400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1b410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b420 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1b430 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1b440 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1b450 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1b460 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b470 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b480 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1b490 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1b4a0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1b4b0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1b4c0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1b4d0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1b4e0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1b4f0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1b500 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1b510 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1b520 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1b530 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1b540 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1b550 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1b560 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1b570 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1b580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1b590 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1b5a0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1b5b0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1b5c0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1b5d0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1b5e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1b5f0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1b600 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1b610 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1b620 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1b630 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1b640 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1b650 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1b660 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1b670 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1b680 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1b690 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1b6a0 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1b6b0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1b6c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
1b6d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1b6e0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1b6f0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1b700 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1b710 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1b720 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1b730 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1b740 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1b750 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1b760 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1b770 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1b780 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1b790 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1b7a0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1b7b0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1b7c0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1b7d0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1b7e0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1b7f0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1b800 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1b810 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1b820 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1b830 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1b840 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1b850 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1b860 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1b870 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1b880 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1b890 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1b8a0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1b8b0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1b8c0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1b8d0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1b8e0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1b8f0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1b900 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1b910 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1b920 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1b930 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1b940 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1b950 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
1b960 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1b970 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1b980 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1b990 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1b9a0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
1b9b0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1b9c0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1b9d0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1b9e0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1b9f0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1ba00 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1ba10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ba20 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1ba30 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1ba40 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1ba50 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1ba60 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1ba70 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1ba80 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1ba90 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1baa0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1bab0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1bac0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1bad0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1bae0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1baf0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1bb00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bb10 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1bb20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1bb30 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1bb40 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1bb50 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1bb60 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1bb70 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1bb80 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1bb90 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1bba0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1bbb0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1bbc0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1bbd0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1bbe0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1bbf0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1bc00 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1bc10 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1bc20 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1bc30 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1bc40 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1bc50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1bc60 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1bc70 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
1bc80 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1bc90 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1bca0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1bcb0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1bcc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bcd0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1bce0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1bcf0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1bd00 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1bd10 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1bd20 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1bd30 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1bd40 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1bd50 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1bd60 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1bd70 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1bd80 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1bd90 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1bda0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1bdb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1bdc0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1bdd0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1bde0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1bdf0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1be00 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1be10 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1be20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1be30 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1be40 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1be50 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1be60 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1be70 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1be80 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1be90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1bea0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1beb0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1bec0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1bed0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1bee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1bef0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1bf00 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1bf10 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1bf20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1bf30 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1bf40 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1bf50 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1bf60 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
1bf70 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1bf80 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1bf90 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1bfa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1bfb0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1bfc0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1bfd0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
1bfe0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1bff0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1c000 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
1c010 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
1c020 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
1c030 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1c040 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1c050 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1c060 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1c070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c080 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1c090 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1c0a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1c0b0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1c0c0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1c0d0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1c0e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1c0f0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1c100 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1c110 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1c120 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1c130 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1c140 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1c150 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1c160 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1c170 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1c180 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1c190 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1c1a0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1c1b0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1c1c0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1c1d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1c1e0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1c1f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1c200 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1c210 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1c220 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1c230 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1c240 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1c250 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1c260 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1c270 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1c280 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1c290 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1c2a0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1c2b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1c2c0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1c2d0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1c2e0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1c2f0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1c300 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1c310 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1c320 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1c330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1c340 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1c350 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1c360 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1c370 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1c380 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1c390 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1c3a0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1c3b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1c3c0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1c3d0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1c3e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1c3f0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1c400 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1c410 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1c420 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1c430 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1c440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c450 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1c460 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1c470 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1c480 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1c490 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1c4a0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1c4b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1c4c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1c4d0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1c4e0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1c4f0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1c500 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1c510 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1c520 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1c530 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1c540 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1c550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c560 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1c570 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1c580 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c590 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1c5a0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1c5b0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1c5c0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1c5d0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1c5e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1c5f0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1c600 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1c610 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1c620 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1c630 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1c640 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
1c650 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1c660 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
1c670 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1c680 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1c690 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1c6a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1c6b0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1c6c0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1c6d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1c6e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1c6f0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1c700 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1c710 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c720 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1c730 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1c740 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1c750 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1c760 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1c770 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1c780 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1c790 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1c7a0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1c7b0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1c7c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1c7d0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1c7e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1c7f0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1c800 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1c810 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1c820 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1c830 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1c840 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
1c850 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1c860 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
1c870 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1c880 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1c890 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
1c8a0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
1c8b0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
1c8c0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
1c8d0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
1c8e0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
1c8f0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
1c900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1c910 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1c920 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
1c930 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1c940 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1c950 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1c960 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1c970 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1c980 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1c990 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
1c9a0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
1c9b0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
1c9c0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
1c9d0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
1c9e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
1c9f0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1ca00 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
1ca10 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1ca20 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
1ca30 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
1ca40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ca50 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
1ca60 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
1ca70 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1ca80 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
1ca90 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
1caa0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
1cab0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
1cac0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1cad0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
1cae0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
1caf0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
1cb00 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
1cb10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cb20 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
1cb30 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1cb40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
1cb50 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
1cb60 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
1cb70 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
1cb80 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1cb90 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
1cba0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
1cbb0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1cbc0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1cbd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cbe0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
1cbf0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
1cc00 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1cc10 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
1cc20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
1cc30 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1cc40 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
1cc50 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1cc60 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
1cc70 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
1cc80 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1cc90 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1cca0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ccb0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
1ccc0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
1ccd0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
1cce0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
1ccf0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
1cd00 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
1cd10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cd20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1cd30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1cd40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
1cd50 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
1cd60 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
1cd70 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1cd80 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
1cd90 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1cda0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
1cdb0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
1cdc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1cdd0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1cde0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1cdf0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1ce00 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1ce10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1ce20 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
1ce30 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
1ce40 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1ce50 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
1ce60 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
1ce70 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1ce80 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
1ce90 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1cea0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1ceb0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1cec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1ced0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1cee0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1cef0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1cf00 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1cf10 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1cf20 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1cf30 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1cf40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1cf50 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1cf60 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1cf70 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1cf80 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1cf90 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1cfa0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1cfb0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1cfc0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1cfd0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1cfe0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1cff0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1d000 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1d010 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
1d020 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1d030 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
1d040 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
1d050 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1d060 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
1d070 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1d080 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1d090 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1d0a0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1d0b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d0c0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1d0d0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1d0e0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
1d0f0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
1d100 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
1d110 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
1d120 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
1d130 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
1d140 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
1d150 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
1d160 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
1d170 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
1d180 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
1d190 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
1d1a0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
1d1b0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1d1c0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1d1d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1d1e0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 69 73 20  ] flag is.** is 
1d1f0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
1d200 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1d210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
1d220 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
1d230 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
1d240 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
1d250 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1d260 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
1d270 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d280 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
1d290 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
1d2a0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
1d2b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1d2c0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
1d2d0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
1d2e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
1d2f0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1d300 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
1d310 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
1d320 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
1d330 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
1d340 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
1d350 65 0a 2a 2a 20 69 6e 74 65 70 72 65 74 61 74 69  e.** intepretati
1d360 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
1d370 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
1d380 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
1d390 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1d3a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
1d3b0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
1d3c0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
1d3d0 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
1d3e0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
1d3f0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
1d400 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
1d410 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
1d420 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
1d430 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
1d440 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
1d450 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
1d460 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1d470 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
1d480 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
1d490 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
1d4a0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
1d4b0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
1d4c0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
1d4d0 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
1d4e0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
1d4f0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
1d500 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
1d510 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
1d520 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
1d530 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
1d540 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
1d550 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
1d560 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
1d570 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
1d580 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
1d590 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
1d5a0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
1d5b0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
1d5c0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
1d5d0 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
1d5e0 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
1d5f0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1d600 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1d610 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
1d620 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
1d630 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
1d640 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
1d650 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
1d660 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
1d670 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
1d680 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
1d690 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
1d6a0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
1d6b0 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
1d6c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
1d6d0 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
1d6e0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1d6f0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
1d700 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
1d710 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
1d720 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
1d730 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
1d740 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
1d750 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1d760 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
1d770 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
1d780 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
1d790 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
1d7a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
1d7b0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
1d7c0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
1d7d0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
1d7e0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
1d7f0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
1d800 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
1d810 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
1d820 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1d830 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
1d840 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
1d850 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
1d860 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1d870 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
1d880 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
1d890 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
1d8a0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
1d8b0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
1d8c0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
1d8d0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1d8e0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
1d8f0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
1d900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1d910 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
1d920 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
1d930 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
1d940 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
1d950 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
1d960 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
1d970 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
1d980 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
1d990 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
1d9a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1d9b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1d9c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
1d9d0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
1d9e0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
1d9f0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1da00 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a  r "ro", "rw" or.
1da10 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74  **     "rwc". At
1da20 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
1da30 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
1da40 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f  value is an erro
1da50 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
1da60 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
1da70 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
1da80 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1da90 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
1daa0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
1dab0 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
1dac0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1dad0 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
1dae0 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
1daf0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
1db00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1db10 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66  repare_v2(). ^If
1db20 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
1db30 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
1db40 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
1db50 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1db60 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
1db70 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
1db80 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
1db90 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
1dba0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1dbb0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
1dbc0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
1dbd0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
1dbe0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
1dbf0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1dc00 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
1dc10 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1dc20 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
1dc30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1dc40 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ATE. ^If sqlite3
1dc50 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a  _open_v2() is .*
1dc60 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69  *     used, it i
1dc70 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1dc80 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1dc90 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  r the mode param
1dca0 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a  eter that is .**
1dcb0 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69       less restri
1dcc0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
1dcd0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1dce0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73   flags passed as
1dcf0 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20   the third .**  
1dd00 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
1dd10 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1dd20 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1dd30 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1dd40 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1dd50 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1dd60 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1dd70 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1dd80 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1dd90 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1dda0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1ddb0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ddc0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1ddd0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1dde0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1ddf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1de00 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1de10 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1de20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1de30 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1de40 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1de50 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1de60 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1de70 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1de80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1de90 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1dea0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1deb0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1dec0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1ded0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1dee0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1def0 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1df00 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1df10 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1df20 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1df30 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1df40 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1df50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1df60 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1df70 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1df80 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1df90 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1dfa0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1dfb0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1dfc0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1dfd0 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1dfe0 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1dff0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1e000 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1e010 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1e020 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1e030 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1e040 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1e050 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1e060 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1e070 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1e080 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1e090 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1e0a0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1e0b0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1e0c0 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1e0d0 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1e0e0 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1e0f0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1e100 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1e110 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1e120 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1e130 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1e140 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1e150 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1e160 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1e170 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1e180 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1e190 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1e1a0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1e1b0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1e1c0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1e1d0 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1e1e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1e1f0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1e200 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1e210 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1e220 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1e230 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1e240 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1e250 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1e260 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1e270 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1e280 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1e290 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1e2a0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1e2b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1e2c0 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1e2d0 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1e2e0 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1e2f0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1e300 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1e310 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1e320 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1e330 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1e340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1e350 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1e360 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1e370 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1e380 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1e390 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1e3a0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1e3b0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1e3c0 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1e3d0 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1e3e0 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1e3f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1e400 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1e410 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1e420 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1e430 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1e440 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1e450 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1e460 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1e470 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1e480 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1e490 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1e4a0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1e4b0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1e4c0 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1e4d0 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1e4e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1e4f0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1e500 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1e510 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1e520 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1e530 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1e540 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1e550 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1e560 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1e570 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1e580 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1e590 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1e5a0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1e5b0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1e5c0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1e5d0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1e5e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1e5f0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1e600 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1e610 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1e620 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1e630 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1e640 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1e650 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1e660 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1e670 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1e680 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1e690 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1e6a0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1e6b0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1e6c0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1e6d0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1e6e0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1e6f0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1e700 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1e710 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1e720 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1e730 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1e740 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1e750 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1e760 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1e770 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1e780 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1e790 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1e7a0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1e7b0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1e7c0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1e7d0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1e7e0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1e7f0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1e800 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1e810 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1e820 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1e830 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1e840 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1e850 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1e860 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1e870 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1e880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e890 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1e8a0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1e8b0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1e8c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1e8d0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1e8e0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1e8f0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1e900 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1e910 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1e920 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1e930 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1e940 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1e950 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1e960 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1e970 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1e980 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e990 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e9a0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1e9b0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1e9c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1e9d0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1e9e0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e9f0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1ea00 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1ea10 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ea20 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1ea30 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1ea40 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1ea50 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1ea60 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1ea70 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1ea80 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1ea90 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1eaa0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1eab0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1eac0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1ead0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1eae0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1eaf0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1eb00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1eb10 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1eb20 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1eb30 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1eb40 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1eb50 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1eb60 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
1eb70 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
1eb80 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
1eb90 68 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79  his is a utility
1eba0 20 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c   routine, useful
1ebb0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
1ebc0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
1ebd0 65 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ecks.** to see i
1ebe0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
1ebf0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
1ec00 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
1ec10 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
1ec20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
1ec30 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
1ec40 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75   value of the qu
1ec50 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
1ec60 2a 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61  *.** The zFilena
1ec70 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  me argument is t
1ec80 68 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  he filename poin
1ec90 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
1eca0 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d  the xOpen().** m
1ecb0 65 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69  ethod of a VFS i
1ecc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1ecd0 54 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d  The zParam argum
1ece0 65 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ent is the name 
1ecf0 6f 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20  of the.** query 
1ed00 70 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65  parameter we see
1ed10 6b 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  k.  This routine
1ed20 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1ed30 75 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d  ue of the zParam
1ed40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
1ed50 20 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20   it exists.  If 
1ed60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f  the parameter do
1ed70 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68  es not exist, th
1ed80 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
1ed90 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1eda0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  nter..**.** If t
1edb0 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67  he zFilename arg
1edc0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75  ument to this fu
1edd0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20  nction is not a 
1ede0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
1edf0 69 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e  ite.** passed in
1ee00 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53  to the xOpen VFS
1ee10 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
1ee20 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
1ee30 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
1ee40 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1ee50 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
1ee60 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
1ee70 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
1ee80 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
1ee90 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
1eea0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
1eeb0 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ram);.../*.** CA
1eec0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1eed0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1eee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1eef0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
1ef00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1ef10 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
1ef20 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
1ef30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ef40 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1ef50 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
1ef60 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
1ef70 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
1ef80 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
1ef90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1efa0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
1efb0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
1efc0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
1efd0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
1efe0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
1eff0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
1f000 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f010 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
1f020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
1f030 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1f040 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1f050 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1f060 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1f070 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1f080 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1f090 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1f0a0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1f0b0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1f0c0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
1f0d0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
1f0e0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
1f0f0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
1f100 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
1f110 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
1f120 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1f130 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
1f140 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1f150 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
1f160 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
1f170 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1f180 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
1f190 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
1f1a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1f1b0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
1f1c0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
1f1d0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
1f1e0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
1f1f0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
1f200 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
1f210 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
1f220 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
1f230 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1f240 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
1f250 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
1f260 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
1f270 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1f280 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
1f290 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
1f2a0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
1f2b0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
1f2c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
1f2d0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1f2e0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
1f2f0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1f300 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1f310 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1f320 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1f330 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1f340 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1f350 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1f360 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1f370 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1f380 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1f390 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1f3a0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1f3b0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1f3c0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1f3d0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1f3e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1f3f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1f400 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1f410 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1f420 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1f430 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1f440 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1f450 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1f460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1f470 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1f480 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1f490 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1f4a0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1f4b0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1f4c0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1f4d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1f4e0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1f4f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1f500 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1f510 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1f520 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1f530 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1f540 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1f550 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1f560 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1f570 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1f580 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
1f590 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1f5a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1f5b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
1f5c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
1f5d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
1f5e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1f5f0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
1f600 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1f610 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1f620 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1f630 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1f640 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
1f650 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1f660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f670 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1f680 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1f690 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1f6a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1f6b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1f6c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1f6d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1f6e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1f6f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1f700 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1f710 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1f720 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1f730 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1f740 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1f750 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1f760 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1f770 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1f780 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1f790 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1f7a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1f7b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f7c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1f7d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1f7e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1f7f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1f800 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1f810 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1f820 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1f830 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1f840 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1f850 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1f860 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1f870 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1f880 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1f890 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1f8a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1f8b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1f8c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1f8d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1f8e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1f8f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1f900 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1f910 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1f920 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1f930 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1f940 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1f950 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1f960 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1f970 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1f980 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1f990 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f9a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1f9b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1f9c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1f9d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
1f9e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1f9f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1fa00 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1fa10 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1fa20 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1fa30 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1fa40 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1fa50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1fa60 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1fa70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1fa80 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1fa90 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1faa0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1fab0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1fac0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1fad0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1fae0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1faf0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1fb00 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1fb10 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1fb20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1fb30 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1fb40 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1fb50 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
1fb60 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1fb70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1fb80 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1fb90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
1fba0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
1fbb0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
1fbc0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
1fbd0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
1fbe0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1fbf0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1fc00 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1fc10 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
1fc20 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
1fc30 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
1fc40 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
1fc50 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
1fc60 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1fc70 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1fc80 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1fc90 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1fca0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1fcb0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1fcc0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1fcd0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1fce0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1fcf0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1fd00 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
1fd10 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1fd20 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
1fd30 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
1fd40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
1fd50 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
1fd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
1fd70 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
1fd80 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
1fd90 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
1fda0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
1fdb0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
1fdc0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
1fdd0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
1fde0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
1fdf0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1fe00 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
1fe10 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1fe20 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1fe30 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1fe40 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1fe50 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1fe60 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1fe70 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1fe80 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1fe90 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1fea0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1feb0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1fec0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1fed0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1fee0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1fef0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1ff00 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1ff10 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1ff20 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1ff30 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1ff40 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1ff50 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1ff60 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1ff70 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1ff80 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1ff90 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1ffa0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1ffb0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1ffc0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1ffd0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1ffe0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1fff0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
20000 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
20010 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
20020 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
20030 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
20040 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
20050 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
20060 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
20070 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20080 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
20090 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
200a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
200b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
200c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
200d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
200e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
200f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
20100 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
20110 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
20120 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
20130 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
20140 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
20150 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
20160 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
20170 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
20180 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
20190 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
201a0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
201b0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
201c0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
201d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
201e0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
201f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
20200 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
20210 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
20220 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
20230 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
20240 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
20250 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
20260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
20270 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
20280 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
20290 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
202a0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
202b0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
202c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
202d0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
202e0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
202f0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
20300 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
20310 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
20320 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
20330 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
20340 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20350 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
20360 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
20370 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
20380 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
20390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
203a0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
203b0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
203c0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
203d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
203e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
203f0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
20400 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
20410 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
20420 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
20430 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
20440 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
20450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20460 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20470 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
20480 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
20490 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
204a0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
204b0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
204c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
204d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
204e0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
204f0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
20500 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
20510 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
20520 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
20530 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
20540 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
20550 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
20560 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
20570 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
20580 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
20590 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
205a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
205b0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
205c0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
205d0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
205e0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
205f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20600 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
20610 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
20620 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
20630 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20640 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
20650 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
20660 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
20670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20680 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20690 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
206a0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
206b0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
206c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
206d0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
206e0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
206f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
20700 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
20710 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
20720 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
20730 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
20740 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
20750 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
20760 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
20770 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
20780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
20790 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
207a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
207b0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
207c0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
207d0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
207e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
207f0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
20800 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
20810 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
20820 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
20830 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
20840 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
20850 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
20860 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
20870 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
20880 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
20890 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
208a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
208b0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
208c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
208d0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
208e0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
208f0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
20900 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
20910 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20920 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
20930 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
20940 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
20950 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
20960 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
20970 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
20980 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
20990 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
209a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
209b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
209c0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
209d0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
209e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
209f0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
20a00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20a10 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
20a20 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
20a30 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
20a40 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
20a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20a60 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
20a70 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
20a80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
20a90 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
20aa0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
20ab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
20ac0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
20ad0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
20ae0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
20af0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
20b00 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
20b10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
20b20 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
20b30 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
20b40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20b50 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
20b60 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
20b70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20b80 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
20b90 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
20ba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20bb0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
20bc0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
20bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20be0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
20bf0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
20c00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20c10 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
20c20 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20c40 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
20c50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
20c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20c70 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
20c80 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
20c90 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
20ca0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
20cb0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
20cc0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
20cd0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
20ce0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
20cf0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
20d00 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
20d10 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
20d20 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
20d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
20d40 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
20d50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20d60 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
20d70 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
20d80 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
20d90 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
20da0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20db0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
20dc0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
20dd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20de0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
20df0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
20e00 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
20e10 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
20e20 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
20e30 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
20e40 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
20e50 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
20e60 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
20e70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20e80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
20e90 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
20ea0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
20eb0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
20ec0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
20ed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20ee0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
20ef0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
20f00 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
20f10 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
20f20 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
20f30 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
20f40 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
20f50 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
20f60 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
20f70 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
20f80 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
20f90 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
20fa0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
20fb0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
20fc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
20fd0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
20fe0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
20ff0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
21000 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
21010 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
21020 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
21030 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
21040 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
21050 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
21060 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
21070 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
21080 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
21090 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
210a0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
210b0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
210c0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
210d0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
210e0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
210f0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
21100 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21110 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
21120 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
21130 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
21140 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
21150 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
21160 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
21170 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
21180 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
21190 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
211a0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
211b0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
211c0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
211d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
211e0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
211f0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
21200 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
21210 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
21220 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
21230 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
21240 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
21250 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
21260 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
21270 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
21280 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
21290 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
212a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
212b0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
212c0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
212d0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
212e0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
212f0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
21300 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
21310 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
21320 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
21330 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
21340 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
21350 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
21360 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
21370 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
21380 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
21390 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
213a0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
213b0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
213c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
213d0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
213e0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
213f0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
21400 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
21410 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
21420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21430 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
21440 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
21450 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
21460 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
21470 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
21480 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
21490 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
214a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
214b0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
214c0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
214d0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
214e0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
214f0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
21500 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
21510 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
21520 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
21530 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
21540 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
21550 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
21560 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
21570 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
21580 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
21590 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
215a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
215b0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
215c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
215d0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
215e0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
215f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
21600 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
21610 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
21620 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
21630 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
21640 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
21650 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
21660 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
21670 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
21680 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
21690 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
216a0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
216b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
216c0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
216d0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
216e0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
216f0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
21700 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c  n it again..** <
21710 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
21720 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
21730 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
21740 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
21750 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
21760 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
21770 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
21780 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
21790 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
217a0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
217b0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
217c0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
217d0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
217e0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
217f0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
21800 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
21810 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
21820 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
21830 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
21840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
21850 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
21860 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
21870 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
21880 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
21890 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
218a0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
218b0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
218c0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
218d0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
218e0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
218f0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
21900 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
21910 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
21920 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
21930 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
21940 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
21950 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
21960 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
21970 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
21980 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
21990 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
219a0 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
219b0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
219c0 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
219d0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
219e0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
219f0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
21a00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21a10 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
21a20 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
21a30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
21a40 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
21a50 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
21a60 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
21a70 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
21a80 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
21a90 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
21aa0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
21ab0 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
21ac0 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
21ad0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
21ae0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
21af0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
21b00 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
21b10 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
21b20 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
21b30 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
21b40 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
21b50 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
21b60 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT2] compile-
21b70 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
21b80 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
21b90 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
21ba0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
21bb0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
21bc0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
21bd0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
21be0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
21bf0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
21c00 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
21c10 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
21c20 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
21c30 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
21c40 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
21c50 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
21c60 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
21c70 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
21c80 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
21c90 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
21ca0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
21cb0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
21cc0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
21cd0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
21ce0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
21cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
21d00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
21d10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
21d20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
21d30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
21d40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
21d50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
21d60 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
21d70 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
21d80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
21d90 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
21da0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
21db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
21dc0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
21dd0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
21de0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
21df0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
21e00 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
21e10 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
21e20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
21e30 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
21e40 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
21e50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
21e60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
21e70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
21e80 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
21e90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
21ea0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
21eb0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
21ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21ed0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
21ee0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
21ef0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
21f00 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
21f10 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
21f20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
21f30 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
21f40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
21f50 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
21f60 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
21f70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
21f80 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
21f90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
21fa0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
21fb0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
21fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
21fd0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
21fe0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
21ff0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
22000 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
22010 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22020 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22030 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
22040 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
22050 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
22060 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
22070 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22080 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
22090 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
220a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
220b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
220c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
220d0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
220e0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
220f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
22100 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
22110 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
22120 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
22130 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
22140 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
22150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22160 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
22170 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
22180 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
22190 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
221a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
221b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
221c0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
221d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
221e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
221f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
22200 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
22210 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
22220 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
22230 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
22240 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
22250 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
22260 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22270 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
22280 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
22290 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
222a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
222b0 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
222c0 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
222d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
222e0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
222f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
22300 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
22310 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
22320 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
22330 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
22340 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
22350 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
22360 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
22370 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
22380 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
22390 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
223a0 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
223b0 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
223c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
223d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
223e0 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
223f0 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
22400 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
22410 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
22420 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
22430 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
22440 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
22450 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
22460 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
22470 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
22480 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
22490 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
224a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
224b0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
224c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
224d0 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
224e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
224f0 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
22500 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
22510 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
22520 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
22530 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
22540 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
22550 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
22560 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
22570 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
22580 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
22590 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
225a0 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
225b0 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
225c0 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
225d0 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
225e0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
225f0 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
22600 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
22610 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
22620 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
22630 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
22640 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
22650 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
22660 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
22670 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
22680 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
22690 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
226a0 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
226b0 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
226c0 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
226d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
226e0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
226f0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
22700 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
22710 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
22720 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
22730 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
22740 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
22750 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
22760 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
22770 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
22780 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
22790 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
227a0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
227b0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
227c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
227d0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
227e0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
227f0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
22800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
22810 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
22820 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
22830 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
22840 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
22850 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
22860 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
22870 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
22880 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
22890 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
228a0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
228b0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
228c0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
228d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
228e0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
228f0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
22900 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
22910 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
22920 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
22930 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
22940 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
22950 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
22960 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
22970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
22980 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
22990 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
229a0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
229b0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
229c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
229d0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
229e0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
229f0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
22a00 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
22a10 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
22a20 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
22a30 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
22a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
22a50 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
22a60 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
22a70 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
22a80 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
22a90 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
22aa0 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
22ab0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
22ac0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
22ad0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
22ae0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
22af0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
22b00 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
22b10 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
22b20 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
22b30 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
22b40 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
22b50 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
22b60 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
22b70 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
22b80 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
22b90 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
22ba0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
22bb0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
22bc0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
22bd0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
22be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
22bf0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
22c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
22c10 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
22c20 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
22c30 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
22c40 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
22c50 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
22c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22c70 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
22c80 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
22c90 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
22ca0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
22cb0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
22cc0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
22cd0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
22ce0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
22cf0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
22d00 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
22d10 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
22d20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
22d30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22d40 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
22d50 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
22d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
22d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22d80 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
22d90 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
22da0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
22db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
22dc0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
22dd0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22de0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
22df0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
22e00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22e10 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
22e20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22e30 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
22e40 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
22e50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22e60 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
22e70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
22e80 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
22e90 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
22ea0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
22eb0 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
22ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
22ed0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
22ee0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
22ef0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
22f00 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
22f10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22f20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
22f30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
22f40 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
22f50 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
22f60 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
22f70 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
22f80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
22f90 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
22fa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
22fb0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
22fc0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
22fd0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
22fe0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
22ff0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
23000 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
23010 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
23020 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
23030 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
23040 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
23050 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
23060 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23070 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
23080 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
23090 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
230a0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
230b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
230c0 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
230d0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
230e0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
230f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
23100 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
23110 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
23120 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
23130 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
23140 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
23150 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
23160 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
23170 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
23180 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
23190 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
231a0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
231b0 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
231c0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
231d0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
231e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
231f0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
23200 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
23210 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
23220 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
23230 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
23240 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
23250 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
23260 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
23270 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
23280 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
23290 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
232a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
232b0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
232c0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
232d0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
232e0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
232f0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
23300 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
23310 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
23320 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
23330 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
23340 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
23350 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
23360 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
23370 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
23380 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
23390 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
233a0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
233b0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
233c0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
233d0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
233e0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
233f0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
23400 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
23410 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
23420 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
23430 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
23440 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
23450 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
23460 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
23470 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
23480 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
23490 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
234a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
234b0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
234c0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
234d0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
234e0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
234f0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
23500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23510 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
23520 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
23530 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
23540 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
23550 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
23560 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
23570 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
23580 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
23590 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
235a0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
235b0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
235c0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
235d0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
235e0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
235f0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
23600 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
23610 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
23620 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
23630 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
23640 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
23650 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
23660 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
23670 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
23680 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
23690 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
236a0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
236b0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
236c0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
236d0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
236e0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
236f0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
23700 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
23710 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
23720 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
23730 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
23740 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
23750 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
23760 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
23770 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
23780 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
23790 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
237a0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
237b0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
237c0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
237d0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
237e0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
237f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
23800 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
23810 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
23820 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
23830 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
23840 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
23850 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
23860 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
23870 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
23880 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
23890 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
238a0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
238b0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
238c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
238d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
238e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
238f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
23900 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
23910 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
23920 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
23930 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
23940 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
23950 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
23960 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
23970 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
23980 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
23990 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
239a0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
239b0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
239c0 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
239d0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
239e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
239f0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
23a00 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
23a10 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
23a20 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
23a30 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
23a40 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
23a50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
23a60 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
23a70 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
23a80 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
23a90 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
23aa0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
23ab0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
23ac0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
23ad0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
23ae0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
23af0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
23b00 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
23b10 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
23b20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
23b30 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
23b40 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
23b50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
23b60 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
23b70 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
23b80 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
23b90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
23ba0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
23bb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
23bc0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
23bd0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
23be0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
23bf0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
23c00 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
23c10 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
23c20 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
23c30 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
23c40 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
23c50 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
23c60 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
23c70 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
23c80 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
23c90 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
23ca0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
23cb0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
23cc0 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
23cd0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
23ce0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
23cf0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
23d00 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
23d10 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
23d20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
23d30 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
23d40 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
23d50 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
23d60 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
23d70 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
23d80 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
23d90 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
23da0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
23db0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
23dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
23dd0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
23de0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
23df0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
23e00 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
23e10 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
23e20 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
23e30 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
23e40 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
23e50 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
23e60 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
23e70 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
23e80 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
23e90 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
23ea0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23eb0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
23ec0 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
23ed0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
23ee0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
23ef0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
23f00 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
23f10 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
23f20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23f30 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
23f40 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
23f50 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
23f60 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
23f70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
23f80 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
23f90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
23fa0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
23fb0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
23fc0 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
23fd0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
23fe0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
23ff0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
24000 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
24010 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
24020 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
24030 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
24040 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
24050 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
24060 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
24070 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
24080 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
24090 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
240a0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
240b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
240c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
240d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
240e0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
240f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
24100 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
24110 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
24120 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
24130 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
24140 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
24150 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
24160 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
24170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24180 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
24190 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
241a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
241b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
241c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
241d0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
241e0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
241f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
24200 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
24210 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
24220 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
24230 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
24240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24250 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
24260 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
24270 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
24280 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
24290 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
242a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
242b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
242c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
242d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
242e0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
242f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
24300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24310 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
24320 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
24330 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
24340 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24350 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
24360 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
24370 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
24380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24390 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
243a0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
243b0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
243c0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
243d0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
243e0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
243f0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
24400 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
24410 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
24420 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
24430 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
24440 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
24450 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
24460 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
24470 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
24480 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
24490 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
244a0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
244b0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
244c0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
244d0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
244e0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
244f0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
24500 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
24510 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
24520 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
24530 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
24540 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
24550 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
24560 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
24570 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
24580 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
24590 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
245a0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
245b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
245c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
245d0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
245e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
245f0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
24600 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
24610 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
24620 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
24630 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
24640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24650 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
24660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24670 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
24680 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
24690 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
246a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
246b0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
246c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
246d0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
246e0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
246f0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
24700 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
24710 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
24720 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
24730 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
24740 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
24750 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
24760 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
24770 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
24780 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
24790 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
247a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
247b0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
247c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
247d0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
247e0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
247f0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
24800 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
24810 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
24820 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
24830 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
24840 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
24850 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
24860 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
24870 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
24880 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
24890 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
248a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
248b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
248c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
248d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
248e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
248f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
24900 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
24910 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
24920 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
24930 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
24940 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
24950 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
24960 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
24970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
24980 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
24990 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
249a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
249b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
249c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
249d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
249e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
249f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24a00 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
24a10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
24a20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24a30 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
24a40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
24a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24a60 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
24a70 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
24a80 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
24a90 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
24aa0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
24ab0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
24ac0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
24ad0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
24ae0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
24af0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
24b00 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
24b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24b20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
24b30 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
24b40 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
24b50 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
24b60 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
24b70 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
24b80 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
24b90 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
24ba0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
24bb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
24bc0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
24bd0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
24be0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24bf0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
24c00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
24c10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24c20 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
24c30 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
24c40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
24c50 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
24c60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24c70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
24c80 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
24c90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24ca0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
24cb0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
24cc0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
24cd0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
24ce0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
24cf0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
24d00 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
24d10 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
24d20 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
24d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24d40 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
24d50 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
24d60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
24d70 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
24d80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24d90 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
24da0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
24db0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
24dc0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
24dd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
24de0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
24df0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
24e00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
24e10 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
24e20 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
24e30 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
24e40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
24e50 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
24e60 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
24e70 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
24e80 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
24e90 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
24ea0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
24eb0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
24ec0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
24ed0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
24ee0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
24ef0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
24f00 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24f10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
24f20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24f30 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
24f40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
24f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24f60 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
24f70 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
24f80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
24f90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
24fa0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
24fb0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
24fc0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
24fd0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
24fe0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
24ff0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
25000 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
25010 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
25020 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25030 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
25040 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
25050 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
25060 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
25070 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
25080 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
25090 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
250a0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
250b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
250c0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
250d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
250e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
250f0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
25100 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
25110 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
25120 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
25130 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
25140 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
25150 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
25160 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25170 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
25180 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
25190 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
251a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
251b0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
251c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
251d0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
251e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
251f0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
25200 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
25210 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
25220 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
25230 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
25240 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
25250 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
25260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
25270 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
25280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
25290 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
252a0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
252b0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
252c0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
252d0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
252e0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
252f0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
25300 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
25310 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
25320 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
25330 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
25340 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
25350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
25360 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
25370 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
25380 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
25390 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
253a0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
253b0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
253c0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
253d0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
253e0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
253f0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
25400 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
25410 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
25420 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
25430 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
25440 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
25450 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25460 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
25470 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
25480 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25490 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
254a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
254b0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
254c0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
254d0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
254e0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
254f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
25500 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
25510 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
25520 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
25530 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
25540 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
25550 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
25560 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
25570 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
25580 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
25590 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
255a0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
255b0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
255c0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
255d0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
255e0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
255f0 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
25600 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
25610 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
25620 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
25630 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
25640 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
25650 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
25660 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
25670 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
25680 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
25690 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
256a0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
256b0 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
256c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
256d0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
256e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
256f0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
25700 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
25710 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
25720 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
25730 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
25740 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
25750 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
25760 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
25770 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
25780 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
25790 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
257a0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
257b0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
257c0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
257d0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
257e0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
257f0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
25800 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
25810 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
25820 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
25830 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
25840 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
25850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25860 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
25870 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
25880 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
25890 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
258a0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
258b0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
258c0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
258d0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
258e0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
258f0 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
25900 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
25910 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
25920 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
25930 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
25940 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
25950 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
25960 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
25970 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
25980 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
25990 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
259a0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
259b0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
259c0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
259d0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
259e0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
259f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
25a00 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
25a10 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
25a20 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
25a30 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
25a40 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
25a50 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
25a60 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
25a70 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
25a80 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
25a90 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
25aa0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
25ab0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
25ac0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
25ad0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
25ae0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
25af0 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
25b00 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
25b10 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
25b20 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
25b30 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
25b40 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
25b50 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
25b60 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
25b70 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
25b80 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
25b90 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
25ba0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
25bb0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
25bc0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
25bd0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
25be0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
25bf0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25c00 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
25c10 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
25c20 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
25c30 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
25c40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
25c50 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
25c60 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
25c70 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
25c80 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
25c90 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
25ca0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
25cb0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
25cc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25cd0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
25ce0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
25cf0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
25d00 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
25d10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
25d20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25d30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
25d40 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
25d50 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25d60 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25d70 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25d80 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
25d90 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25da0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25db0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
25dc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25dd0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
25de0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25df0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
25e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25e10 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
25e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
25e30 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
25e40 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25e50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25e60 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
25e70 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25e80 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
25e90 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
25ea0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
25eb0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
25ec0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
25ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25ef0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
25f00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
25f10 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
25f20 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
25f30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
25f40 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
25f50 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
25f60 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
25f70 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
25f80 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
25f90 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
25fa0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
25fb0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
25fc0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
25fd0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
25fe0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
25ff0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
26000 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
26010 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
26020 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
26030 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
26040 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
26050 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
26060 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
26070 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
26080 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
26090 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
260a0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
260b0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
260c0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
260d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
260e0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
260f0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
26100 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
26110 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
26120 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
26130 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
26140 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
26150 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
26160 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
26170 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
26180 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
26190 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
261a0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
261b0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
261c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
261d0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
261e0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
261f0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
26200 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
26210 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
26220 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
26230 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
26240 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
26250 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
26260 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
26270 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
26280 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
26290 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
262a0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
262b0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
262c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
262d0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
262e0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
262f0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
26300 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
26310 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
26320 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
26330 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
26340 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26350 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26370 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
26380 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
26390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
263a0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
263b0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
263c0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
263d0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
263e0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
263f0 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
26400 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26410 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
26420 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
26430 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
26440 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
26450 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
26460 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
26470 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
26480 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
26490 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
264a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
264b0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
264c0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
264d0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
264e0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
264f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
26500 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
26510 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
26520 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
26530 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
26540 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
26550 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
26560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26570 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
26580 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26590 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
265a0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
265b0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
265c0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
265d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
265e0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
265f0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
26600 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
26610 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
26620 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
26630 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
26640 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
26650 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
26660 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
26670 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
26680 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
26690 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
266a0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
266b0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
266c0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
266d0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
266e0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
266f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
26700 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
26710 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
26720 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
26730 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
26740 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
26750 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
26760 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
26770 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
26780 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
26790 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
267a0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
267b0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
267c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
267d0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
267e0 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
267f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26800 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
26810 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
26820 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
26830 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
26840 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
26850 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
26860 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
26870 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
26880 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
26890 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
268a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
268b0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
268c0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
268d0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
268e0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
268f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
26900 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
26910 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
26920 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
26930 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
26940 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
26950 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
26960 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
26970 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
26980 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
26990 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
269a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
269b0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
269c0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
269d0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
269e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
269f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
26a00 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
26a10 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
26a20 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
26a30 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
26a40 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
26a50 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
26a60 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
26a70 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
26a80 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
26a90 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
26aa0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
26ab0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
26ac0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
26ad0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
26ae0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
26af0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
26b00 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
26b10 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
26b20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
26b30 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
26b40 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
26b50 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
26b60 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
26b70 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
26b80 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
26b90 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
26ba0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
26bb0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
26bc0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
26bd0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
26be0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
26bf0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
26c00 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
26c10 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
26c20 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
26c30 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
26c40 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
26c50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26c60 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
26c70 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
26c80 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
26c90 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
26ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26cb0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
26cc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26cd0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
26ce0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
26cf0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
26d00 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
26d10 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
26d20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
26d30 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
26d40 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
26d50 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
26d60 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
26d70 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
26d80 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
26d90 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
26da0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26db0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
26dc0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
26dd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
26de0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
26df0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
26e00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
26e10 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
26e20 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
26e30 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
26e40 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
26e50 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
26e60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26e70 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
26e80 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
26e90 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
26ea0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
26eb0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
26ec0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
26ed0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
26ee0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
26ef0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
26f00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
26f10 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
26f20 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
26f30 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
26f40 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
26f50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
26f60 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
26f70 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
26f80 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
26f90 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
26fa0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
26fb0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
26fc0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
26fd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26fe0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
26ff0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
27000 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
27010 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
27020 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
27030 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
27040 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
27050 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
27060 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27070 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
27080 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
27090 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
270a0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
270b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
270c0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
270d0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
270e0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
270f0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
27100 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
27110 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
27120 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
27130 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
27140 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
27150 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
27160 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
27170 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
27180 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
27190 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
271a0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
271b0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
271c0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
271d0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
271e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
271f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
27200 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
27210 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
27220 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
27230 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
27240 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
27250 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
27260 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
27270 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
27280 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
27290 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
272a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
272b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
272c0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
272d0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
272e0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
272f0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
27300 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27310 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
27320 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
27330 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
27340 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
27350 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
27360 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
27370 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
27380 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
27390 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
273a0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
273b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
273c0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
273d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
273e0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
273f0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
27400 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
27410 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
27420 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
27430 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
27440 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
27450 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
27460 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
27470 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
27480 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
27490 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
274a0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
274b0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
274c0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
274d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
274e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
274f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
27500 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
27510 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27520 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
27530 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27540 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
27550 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
27560 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
27570 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
27580 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
27590 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
275a0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
275b0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
275c0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
275d0 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
275e0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
275f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27600 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
27610 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
27620 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
27630 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
27640 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
27650 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
27660 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
27670 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
27680 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
27690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
276a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
276b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
276c0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
276d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
276e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
276f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27700 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
27710 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
27720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
27730 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
27740 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
27750 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
27760 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
27770 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
27780 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
27790 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
277a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
277b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
277c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
277d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
277e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
277f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
27800 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
27810 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
27820 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
27830 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
27840 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
27850 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
27860 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
27870 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
27880 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
27890 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
278a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
278b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
278c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
278d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
278e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
278f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
27900 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
27910 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
27920 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
27930 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
27940 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
27950 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
27960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
27970 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
27980 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
27990 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
279a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
279b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
279c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
279d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
279e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
279f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
27a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27a10 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
27a20 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
27a30 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
27a40 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
27a50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27a60 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
27a70 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
27a80 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
27a90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
27aa0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
27ab0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
27ac0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
27ad0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
27ae0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
27af0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
27b00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27b10 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
27b20 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
27b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
27b40 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
27b50 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
27b60 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
27b70 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
27b80 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
27b90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
27ba0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
27bb0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
27bc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
27bd0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27be0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
27bf0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
27c00 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
27c10 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
27c20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
27c30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
27c40 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
27c50 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
27c60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
27c70 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
27c80 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
27c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
27ca0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
27cb0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
27cc0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
27cd0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
27ce0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
27cf0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
27d00 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
27d10 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
27d20 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
27d30 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
27d40 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
27d50 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
27d60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
27d70 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
27d80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
27d90 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
27da0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
27db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
27dc0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
27dd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
27de0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
27df0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
27e00 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
27e10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
27e20 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
27e30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
27e40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
27e50 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
27e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27e70 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
27e80 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
27e90 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
27ea0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
27eb0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
27ec0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
27ed0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
27ee0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
27ef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27f00 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
27f10 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
27f20 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
27f30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
27f40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
27f50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
27f60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27f70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
27f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27f90 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
27fa0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
27fb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
27fc0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
27fd0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
27fe0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
27ff0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
28000 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
28010 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
28020 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
28030 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
28040 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
28050 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
28060 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
28070 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
28080 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
28090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
280a0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
280b0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
280c0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
280d0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
280e0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
280f0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
28100 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
28110 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
28120 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
28130 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
28140 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
28150 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
28160 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
28170 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
28180 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
28190 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
281a0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
281b0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
281c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
281d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
281e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
281f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
28200 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
28210 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
28220 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28230 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
28240 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
28250 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
28260 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
28270 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28280 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
28290 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
282a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
282b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
282c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
282d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
282e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
282f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
28300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28310 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
28320 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
28330 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
28340 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
28350 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
28360 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
28380 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
283a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
283b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
283c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
283d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
283e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
283f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
28400 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
28410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
28420 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
28430 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
28440 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
28450 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
28460 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28470 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
28480 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
28490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
284a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
284b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
284c0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
284d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
284e0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
284f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
28500 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
28510 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28520 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
28530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
28540 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
28550 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
28560 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
28570 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
28580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
28590 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
285a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
285b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
285c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
285d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
285e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
285f0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
28600 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
28610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28620 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
28630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28640 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
28650 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
28660 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
28670 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
28680 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
28690 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
286a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
286b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
286c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
286d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
286e0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
286f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
28700 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
28710 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
28720 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
28730 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
28740 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
28750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
28760 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28770 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
28780 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
28790 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
287a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
287b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
287c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
287d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
287e0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
287f0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
28800 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
28810 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
28820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
28830 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
28840 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
28850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28860 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
28870 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
28880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28890 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
288a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
288b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
288c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
288d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
288e0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
288f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28910 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
28920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
28930 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
28940 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
28950 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
28960 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
28970 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
28980 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
28990 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
289a0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
289b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
289c0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
289d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
289e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
289f0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
28a00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
28a10 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
28a20 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
28a30 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
28a40 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
28a50 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
28a60 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
28a70 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
28a80 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
28a90 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
28aa0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
28ab0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
28ac0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
28ad0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
28ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
28af0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
28b00 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
28b10 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
28b20 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28b30 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
28b40 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
28b50 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
28b60 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
28b70 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
28b80 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
28b90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28ba0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
28bb0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28bc0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
28bd0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
28be0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
28bf0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
28c00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28c10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28c20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28c30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28c40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28c50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28c60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28c70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28c80 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
28c90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
28ca0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
28cb0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
28cc0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
28cd0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
28ce0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
28cf0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
28d00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
28d10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
28d20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28d30 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
28d40 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
28d50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
28d60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28d70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
28d80 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
28d90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
28da0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
28db0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
28dc0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
28dd0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
28de0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
28df0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
28e00 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
28e10 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
28e20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
28e30 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
28e40 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
28e50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
28e60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28e70 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
28e80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
28e90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28ea0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
28eb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
28ec0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
28ed0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
28ee0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
28ef0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
28f00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
28f10 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28f20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
28f30 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
28f40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
28f50 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
28f60 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
28f70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
28f80 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
28f90 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
28fa0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
28fb0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
28fc0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
28fd0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
28fe0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
28ff0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
29000 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
29010 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
29020 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
29030 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
29040 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
29050 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
29060 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
29070 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
29080 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
29090 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
290a0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
290b0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
290c0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
290d0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
290e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
290f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
29100 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
29110 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
29120 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
29130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29140 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
29150 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
29160 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
29170 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29180 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
29190 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
291a0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
291b0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
291c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
291d0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
291e0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
291f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
29200 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29210 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
29220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29230 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
29240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29250 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
29260 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
29270 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
29280 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
29290 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
292a0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
292b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
292c0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
292d0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
292e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
292f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
29300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29310 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
29320 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
29330 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
29340 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
29350 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
29360 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29370 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
29380 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
29390 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
293a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
293b0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
293c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
293d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
293e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
293f0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
29400 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
29410 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
29420 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
29430 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
29440 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
29450 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
29460 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
29470 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
29480 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
29490 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
294a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
294b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
294c0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
294d0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
294e0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
294f0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
29500 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
29510 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
29520 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
29530 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
29540 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
29550 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
29560 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
29570 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
29580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
29590 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
295a0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
295b0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
295c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
295d0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
295e0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
295f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
29600 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
29610 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
29620 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
29630 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
29640 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
29650 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
29660 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
29670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
29680 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
29690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
296a0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
296b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
296c0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
296d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
296e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
296f0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
29700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29710 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
29720 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
29730 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
29740 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
29750 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
29760 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
29770 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
29780 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
29790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
297a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
297b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
297c0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
297d0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
297e0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
297f0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
29800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
29810 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
29820 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
29830 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
29840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29850 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
29860 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
29870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29880 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
29890 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
298a0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
298b0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
298c0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
298d0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
298e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
298f0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
29900 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
29910 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
29920 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29930 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
29940 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29950 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
29960 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
29970 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
29980 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
29990 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
299a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
299b0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
299c0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
299d0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
299e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
299f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
29a00 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
29a10 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
29a20 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
29a30 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
29a40 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
29a50 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
29a60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
29a70 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
29a80 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
29a90 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
29aa0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
29ab0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
29ac0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
29ad0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
29ae0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
29af0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
29b00 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
29b10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
29b20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
29b30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
29b40 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
29b50 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
29b60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29b70 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
29b80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29b90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
29ba0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
29bb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
29bc0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
29bd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
29be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29bf0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
29c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
29c10 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
29c20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
29c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
29c40 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
29c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29c60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
29c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
29c80 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
29c90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
29ca0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
29cb0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29cc0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
29cd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29ce0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29d00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29d10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
29d20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29d30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
29d40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
29d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
29d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
29d70 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
29d80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
29d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
29da0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
29db0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
29dc0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
29dd0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
29de0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
29df0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
29e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e10 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
29e20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
29e30 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
29e40 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
29e50 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72  red no errors or
29e60 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
29e70 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
29e80 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
29e90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
29ea0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
29eb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
29ec0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
29ed0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
29ee0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
29ef0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
29f00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
29f10 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
29f20 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
29f30 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
29f40 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
29f50 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
29f60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29f70 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
29f80 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
29f90 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
29fa0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
29fb0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
29fc0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
29fd0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
29fe0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
29ff0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2a000 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2a010 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a020 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2a030 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2a040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2a050 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2a060 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2a070 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2a080 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2a090 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2a0a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2a0b0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2a0c0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2a0d0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2a0e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2a0f0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2a100 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2a110 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2a120 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2a130 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2a140 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2a150 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2a160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2a170 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2a180 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a190 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2a1a0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2a1b0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2a1c0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2a1d0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2a1e0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2a1f0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2a200 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2a210 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2a220 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2a230 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2a240 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2a250 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2a260 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2a270 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2a280 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2a290 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2a2a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2a2b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2a2c0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2a2d0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2a2e0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2a2f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2a300 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2a310 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2a320 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2a330 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2a340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2a350 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2a360 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2a370 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2a380 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a390 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2a3a0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2a3b0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2a3c0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2a3d0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2a3e0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2a3f0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2a400 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2a410 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2a420 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2a430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a440 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2a450 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2a460 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2a470 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2a480 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2a490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2a4a0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2a4b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a4c0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2a4d0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2a4e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2a4f0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2a500 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2a510 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2a520 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2a530 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2a540 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2a550 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2a560 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2a570 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a580 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a590 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2a5a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a5b0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2a5c0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2a5d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2a5e0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2a5f0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2a600 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2a610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2a620 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2a630 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2a640 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2a650 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2a660 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2a670 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2a680 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2a690 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2a6a0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2a6b0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a6c0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2a6d0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2a6e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2a6f0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2a700 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2a710 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2a720 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2a730 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2a740 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2a750 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2a760 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2a770 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2a780 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2a790 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2a7a0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2a7b0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2a7c0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2a7d0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2a7e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2a7f0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2a800 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2a810 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2a820 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2a830 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2a840 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2a850 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2a860 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2a870 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2a880 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2a890 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2a8a0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2a8b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2a8c0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2a8d0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2a8e0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2a8f0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2a900 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2a910 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2a920 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2a930 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2a940 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2a950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a960 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2a970 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2a980 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2a990 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2a9a0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2a9b0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2a9c0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2a9d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2a9e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a9f0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2aa00 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2aa10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2aa20 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2aa30 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2aa40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2aa50 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2aa60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2aa70 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2aa80 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2aa90 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2aaa0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2aab0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2aac0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2aad0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2aae0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2aaf0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2ab00 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2ab10 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2ab20 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2ab30 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2ab40 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2ab50 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2ab60 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2ab70 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2ab80 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2ab90 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2aba0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2abb0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2abc0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2abd0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2abe0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2abf0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2ac00 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2ac10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2ac20 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2ac30 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2ac40 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2ac50 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2ac60 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2ac70 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2ac80 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2ac90 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2aca0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2acb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2acc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2acd0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2ace0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2acf0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2ad00 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2ad10 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2ad20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2ad30 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2ad40 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2ad50 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2ad60 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2ad70 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2ad80 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2ad90 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2ada0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2adb0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2adc0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2add0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2ade0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2adf0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2ae00 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2ae10 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2ae20 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2ae30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2ae40 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2ae50 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2ae60 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2ae70 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2ae80 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2ae90 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2aea0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2aeb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2aec0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2aed0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2aee0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2aef0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2af00 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2af10 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2af20 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2af30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2af40 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2af50 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2af60 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2af70 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2af80 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2af90 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2afa0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2afb0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2afc0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2afd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2afe0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2aff0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2b000 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2b010 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2b020 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2b030 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2b040 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2b050 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2b060 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2b070 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2b080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2b090 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2b0a0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2b0b0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2b0c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2b0d0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2b0e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2b0f0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2b100 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2b110 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2b120 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2b130 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2b140 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2b150 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2b160 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b170 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2b180 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2b190 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2b1a0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2b1b0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2b1c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2b1d0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2b1e0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2b1f0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2b200 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2b210 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2b220 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2b230 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2b240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2b250 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2b260 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2b270 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2b280 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2b290 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2b2a0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2b2b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2b2c0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2b2d0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2b2e0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2b2f0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2b300 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2b310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2b320 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b330 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2b340 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2b350 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2b360 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2b370 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2b380 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2b390 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2b3a0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2b3b0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2b3c0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2b3d0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2b3e0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2b3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2b400 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2b410 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2b420 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2b430 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2b440 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b450 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2b460 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2b470 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2b480 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2b490 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2b4a0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2b4b0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2b4c0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2b4d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2b4e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2b4f0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2b500 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2b510 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2b520 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b530 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2b540 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2b550 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2b560 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2b570 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2b580 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2b590 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2b5a0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2b5b0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2b5c0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2b5d0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2b5e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2b5f0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2b600 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2b610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2b620 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2b630 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2b640 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2b650 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2b660 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2b670 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2b680 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2b690 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2b6a0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2b6b0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2b6c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2b6d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2b6e0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2b6f0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2b700 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2b710 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2b720 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2b730 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2b740 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2b750 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2b760 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2b770 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2b780 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2b790 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2b7a0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2b7b0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2b7c0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2b7d0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2b7e0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2b7f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2b800 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2b810 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2b820 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2b830 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2b840 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2b850 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2b860 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2b870 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b880 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2b890 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2b8a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b8b0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2b8c0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2b8d0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2b8e0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2b8f0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2b900 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2b910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b920 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2b930 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2b940 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2b950 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2b960 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2b970 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
2b980 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b990 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2b9a0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2b9b0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2b9c0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2b9d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2b9e0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2b9f0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2ba00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2ba10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ba20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2ba30 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2ba40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2ba50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2ba60 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2ba70 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2ba80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2ba90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2baa0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2bab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2bac0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2bad0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2bae0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2baf0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2bb00 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2bb10 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2bb20 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2bb30 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2bb40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2bb50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2bb60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2bb70 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2bb80 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2bb90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bba0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2bbb0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2bbc0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2bbd0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2bbe0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2bbf0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2bc00 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2bc10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2bc20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2bc30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2bc40 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2bc50 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2bc60 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2bc70 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2bc80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2bc90 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2bca0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2bcb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2bcc0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2bcd0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2bce0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2bcf0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2bd00 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2bd10 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2bd20 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2bd30 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2bd40 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2bd50 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2bd60 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2bd70 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2bd80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2bd90 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2bda0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2bdb0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2bdc0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2bdd0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2bde0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2bdf0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2be00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2be10 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2be20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2be30 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2be40 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2be50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2be60 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2be70 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2be80 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2be90 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2bea0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2beb0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2bec0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2bed0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2bee0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2bef0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2bf00 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2bf10 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2bf20 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2bf30 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2bf40 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2bf50 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2bf60 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2bf70 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2bf80 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2bf90 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2bfa0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2bfb0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2bfc0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2bfd0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2bfe0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2bff0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2c000 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2c010 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2c020 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2c030 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2c040 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2c050 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2c060 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2c070 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2c080 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2c090 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2c0a0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2c0b0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2c0c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2c0d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2c0e0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2c0f0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2c100 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2c110 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2c120 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2c130 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2c140 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2c150 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2c160 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2c170 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2c180 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2c190 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2c1a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2c1b0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2c1c0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2c1d0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2c1e0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2c1f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2c200 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2c210 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2c220 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2c230 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2c240 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2c250 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2c260 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2c270 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2c280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2c290 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2c2a0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2c2b0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2c2c0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2c2d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2c2e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2c2f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2c300 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2c310 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2c320 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2c330 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2c340 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2c350 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2c360 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2c370 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2c380 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2c390 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2c3a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c3b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2c3c0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2c3d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c3e0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2c3f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2c400 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2c410 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2c420 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2c430 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2c440 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2c450 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2c460 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2c470 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2c480 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2c490 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c4a0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2c4b0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2c4c0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2c4d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2c4e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2c4f0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2c500 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2c510 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2c520 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2c530 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2c540 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2c550 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2c560 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2c570 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2c580 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2c590 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2c5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c5b0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2c5c0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2c5d0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2c5e0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2c5f0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2c600 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2c610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c620 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2c630 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2c640 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2c650 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2c660 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2c670 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2c680 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2c690 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2c6a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c6b0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2c6c0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2c6d0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2c6e0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2c6f0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2c700 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2c710 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2c720 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2c730 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2c740 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2c750 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2c760 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2c770 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2c780 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2c790 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2c7a0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2c7b0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2c7c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2c7d0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2c7e0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2c7f0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2c800 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2c810 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2c820 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2c830 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2c840 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2c850 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2c860 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2c870 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2c880 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2c890 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2c8a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2c8b0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2c8c0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2c8d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2c8e0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2c8f0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2c900 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2c910 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2c920 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2c930 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2c940 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2c950 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2c960 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2c970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2c980 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2c990 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2c9a0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2c9b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c9c0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2c9d0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2c9e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2c9f0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2ca00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2ca10 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2ca20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ca30 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2ca40 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2ca50 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2ca60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2ca70 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2ca80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2ca90 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
2caa0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cab0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2cac0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2cad0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2cae0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2caf0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2cb00 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2cb10 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2cb20 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2cb30 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2cb40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cb50 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2cb60 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2cb70 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2cb80 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2cb90 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2cba0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2cbb0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2cbc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cbd0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2cbe0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cbf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cc00 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2cc10 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2cc20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2cc30 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2cc40 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2cc50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2cc60 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2cc70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2cc80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2cc90 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2cca0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2ccb0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2ccc0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2ccd0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2cce0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2ccf0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2cd00 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
2cd10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2cd20 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2cd30 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2cd40 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
2cd50 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
2cd60 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2cd70 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
2cd80 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2cd90 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2cda0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2cdb0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
2cdc0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
2cdd0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2cde0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
2cdf0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
2ce00 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
2ce10 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
2ce20 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2ce30 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2ce40 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
2ce50 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
2ce60 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2ce70 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2ce80 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ce90 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
2cea0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2ceb0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
2cec0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
2ced0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
2cee0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2cef0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
2cf00 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
2cf10 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
2cf20 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
2cf30 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
2cf40 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
2cf50 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
2cf60 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
2cf70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
2cf80 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
2cf90 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
2cfa0 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
2cfb0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
2cfc0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
2cfd0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
2cfe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
2cff0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
2d000 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
2d010 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
2d020 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
2d030 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
2d040 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2d050 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
2d060 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
2d070 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
2d080 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
2d090 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d0a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2d0b0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
2d0c0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2d0d0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
2d0e0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
2d0f0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
2d100 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2d110 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
2d120 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
2d130 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
2d140 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
2d150 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d160 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
2d170 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
2d180 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
2d190 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
2d1a0 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
2d1b0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
2d1c0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
2d1d0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2d1e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2d1f0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
2d200 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
2d210 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2d220 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
2d230 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
2d240 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
2d250 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2d260 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2d270 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
2d280 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
2d290 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2d2a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
2d2b0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
2d2c0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
2d2d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2d2e0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2d2f0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
2d300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2d310 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
2d320 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
2d330 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
2d340 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
2d350 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
2d360 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
2d370 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
2d380 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
2d390 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
2d3a0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2d3b0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
2d3c0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2d3d0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2d3e0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
2d3f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2d400 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2d410 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
2d420 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
2d430 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2d440 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
2d450 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
2d460 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
2d470 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
2d480 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2d490 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2d4a0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2d4b0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
2d4c0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
2d4d0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
2d4e0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2d4f0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
2d500 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d510 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
2d520 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d530 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
2d540 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
2d550 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
2d560 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
2d570 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2d580 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2d590 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2d5a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2d5b0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2d5c0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2d5d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d5e0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2d5f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2d600 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2d610 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2d620 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d630 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2d640 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2d650 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
2d660 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
2d670 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
2d680 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d690 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2d6a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
2d6b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d6c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
2d6d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2d6e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2d6f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2d700 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2d710 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d720 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2d730 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2d740 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2d750 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2d760 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2d770 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2d780 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2d790 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
2d7a0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2d7b0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
2d7c0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
2d7d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
2d7e0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
2d7f0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
2d800 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
2d810 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
2d820 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
2d830 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
2d840 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
2d850 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
2d860 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
2d870 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2d880 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
2d890 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
2d8a0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
2d8b0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
2d8c0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
2d8d0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
2d8e0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
2d8f0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
2d900 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
2d910 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
2d920 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
2d930 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
2d940 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
2d950 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
2d960 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
2d970 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
2d980 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
2d990 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2d9a0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
2d9b0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
2d9c0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
2d9d0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
2d9e0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
2d9f0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2da00 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
2da10 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
2da20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2da30 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2da40 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
2da50 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
2da60 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
2da70 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
2da80 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
2da90 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
2daa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
2dab0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2dac0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2dad0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
2dae0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
2daf0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
2db00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2db10 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
2db20 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2db30 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
2db40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2db50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
2db60 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
2db70 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
2db80 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
2db90 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
2dba0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
2dbb0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
2dbc0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
2dbd0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
2dbe0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
2dbf0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
2dc00 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
2dc10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2dc20 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
2dc30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2dc40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dc50 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
2dc60 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
2dc70 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
2dc80 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2dc90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2dca0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
2dcb0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
2dcc0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
2dcd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dce0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
2dcf0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2dd00 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
2dd10 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
2dd20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
2dd30 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
2dd40 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
2dd50 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
2dd60 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
2dd70 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2dd80 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
2dd90 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
2dda0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2ddb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
2ddc0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
2ddd0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
2dde0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
2ddf0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
2de00 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2de10 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
2de20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2de30 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
2de40 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
2de50 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
2de60 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
2de70 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
2de80 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
2de90 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
2dea0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
2deb0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
2dec0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
2ded0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
2dee0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
2def0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
2df00 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
2df10 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
2df20 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
2df30 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
2df40 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
2df50 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
2df60 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
2df70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
2df80 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
2df90 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
2dfa0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
2dfb0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
2dfc0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
2dfd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2dfe0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2dff0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2e000 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2e010 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2e020 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2e030 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
2e040 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2e050 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
2e060 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
2e070 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2e080 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2e090 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
2e0a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
2e0b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2e0c0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
2e0d0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
2e0e0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
2e0f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2e100 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
2e110 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2e120 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2e130 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2e140 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2e150 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2e160 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2e170 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
2e180 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2e190 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2e1a0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2e1b0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2e1c0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2e1d0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2e1e0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2e1f0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2e200 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2e210 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
2e220 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
2e230 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
2e240 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
2e250 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
2e260 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
2e270 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
2e280 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
2e290 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2e2a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
2e2b0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
2e2c0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
2e2d0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
2e2e0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
2e2f0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
2e300 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
2e310 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
2e320 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
2e330 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
2e340 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2e350 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
2e360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e370 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
2e380 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2e390 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
2e3a0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2e3b0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
2e3c0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
2e3d0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
2e3e0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
2e3f0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
2e400 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
2e410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e420 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
2e430 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
2e440 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
2e450 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
2e460 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2e470 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
2e480 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e490 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2e4a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e4b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2e4c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2e4d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2e4e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2e4f0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
2e500 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
2e510 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
2e520 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
2e530 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
2e540 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
2e550 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
2e560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e570 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
2e580 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
2e590 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
2e5a0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
2e5b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2e5c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e5d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
2e5e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2e5f0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2e600 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2e610 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2e620 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
2e630 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
2e640 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
2e650 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
2e660 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
2e670 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
2e680 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
2e690 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
2e6a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2e6b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2e6c0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
2e6d0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
2e6e0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2e6f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e700 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2e710 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
2e720 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
2e730 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
2e740 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
2e750 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
2e760 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
2e770 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2e780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2e790 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
2e7a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2e7b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2e7c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e7d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2e7e0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2e7f0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2e800 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
2e810 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2e820 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2e830 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2e840 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2e850 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2e860 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2e870 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2e880 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2e890 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2e8a0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
2e8b0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
2e8c0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
2e8d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2e8e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2e8f0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
2e900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2e910 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
2e920 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
2e930 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
2e940 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
2e950 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2e960 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
2e970 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2e980 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
2e990 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2e9a0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2e9b0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2e9c0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2e9d0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
2e9e0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
2e9f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2ea00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2ea10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ea20 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2ea30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2ea40 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
2ea50 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
2ea60 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2ea70 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
2ea80 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2ea90 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2eaa0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2eab0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2eac0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2ead0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
2eae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2eaf0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
2eb00 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2eb10 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
2eb20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
2eb30 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
2eb40 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2eb50 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
2eb60 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
2eb70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2eb80 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2eb90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2eba0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
2ebb0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
2ebc0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
2ebd0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2ebe0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
2ebf0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
2ec00 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
2ec10 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
2ec20 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
2ec30 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
2ec40 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
2ec50 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
2ec60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ec70 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2ec80 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2ec90 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2eca0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2ecb0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2ecc0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2ecd0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
2ece0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
2ecf0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
2ed00 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
2ed10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2ed20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2ed30 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2ed40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ed50 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
2ed60 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2ed70 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
2ed80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ed90 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
2eda0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
2edb0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
2edc0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
2edd0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2ede0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2edf0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
2ee00 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
2ee10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2ee20 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2ee30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2ee40 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2ee50 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2ee60 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
2ee70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2ee80 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
2ee90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2eea0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
2eeb0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2eec0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2eed0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2eee0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2eef0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
2ef00 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2ef10 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
2ef20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
2ef30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ef40 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
2ef50 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2ef60 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2ef70 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2ef80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ef90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2efa0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
2efb0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2efc0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2efd0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2efe0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2eff0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
2f000 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f010 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2f020 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f030 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f040 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
2f050 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f060 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2f070 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2f080 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
2f090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f0a0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2f0b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f0c0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2f0d0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2f0e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2f0f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f100 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f110 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2f120 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2f130 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2f140 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2f150 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2f160 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2f170 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2f180 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2f190 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
2f1a0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2f1b0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2f1c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f1d0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2f1e0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2f1f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f200 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2f210 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
2f220 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2f230 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f240 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2f250 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
2f260 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
2f270 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
2f280 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2f290 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
2f2a0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2f2b0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2f2c0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2f2d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2f2e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f2f0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2f300 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2f310 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
2f320 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
2f330 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
2f340 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
2f350 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2f360 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
2f370 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f380 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
2f390 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
2f3a0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2f3b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2f3c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f3d0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2f3e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2f3f0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
2f400 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2f410 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
2f420 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
2f430 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
2f440 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
2f450 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
2f460 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2f470 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2f480 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2f490 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2f4a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2f4b0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2f4c0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
2f4d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2f4e0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
2f4f0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
2f500 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
2f510 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
2f520 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
2f530 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2f540 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
2f550 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2f560 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
2f570 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
2f580 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
2f590 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
2f5a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
2f5b0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
2f5c0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2f5d0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2f5e0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2f5f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2f600 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2f610 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2f620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2f630 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2f640 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2f650 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
2f660 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
2f670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
2f680 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
2f690 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
2f6a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2f6b0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
2f6c0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
2f6d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f6e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2f6f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f700 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
2f710 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f720 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f730 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
2f740 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2f750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f760 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
2f770 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2f780 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
2f790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2f7a0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2f7b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2f7c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2f7d0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
2f7e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2f7f0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
2f800 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
2f810 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
2f820 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
2f830 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
2f840 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
2f850 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
2f860 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
2f870 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f880 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
2f890 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
2f8a0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2f8b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f8c0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
2f8d0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
2f8e0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
2f8f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f900 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
2f910 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
2f920 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
2f930 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2f940 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
2f950 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
2f960 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
2f970 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
2f980 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
2f990 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f9a0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
2f9b0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
2f9c0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
2f9d0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
2f9e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f9f0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2fa00 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
2fa10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2fa20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2fa30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2fa40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2fa50 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
2fa60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
2fa70 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
2fa80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2fa90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2faa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2fab0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2fac0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2fad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fae0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2faf0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2fb00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2fb10 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
2fb20 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2fb30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2fb40 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
2fb50 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2fb60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fb70 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
2fb80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2fb90 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2fba0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
2fbb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2fbc0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2fbd0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
2fbe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fbf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2fc00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2fc10 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
2fc20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2fc30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fc40 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2fc50 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
2fc60 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
2fc70 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2fc80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fc90 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
2fca0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2fcb0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2fcc0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2fcd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fce0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
2fcf0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2fd00 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2fd10 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2fd20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fd30 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2fd40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2fd50 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2fd60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2fd70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fd80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
2fd90 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
2fda0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
2fdb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2fdc0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
2fdd0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
2fde0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fdf0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
2fe00 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
2fe10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2fe20 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
2fe30 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
2fe40 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
2fe50 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
2fe60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2fe70 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
2fe80 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2fe90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2fea0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2feb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
2fec0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2fed0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2fee0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2fef0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2ff00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2ff10 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2ff20 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
2ff30 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
2ff40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ff50 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
2ff60 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
2ff70 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
2ff80 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
2ff90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
2ffa0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
2ffb0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
2ffc0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
2ffd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
2ffe0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
2fff0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
30000 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
30010 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
30020 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
30030 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
30040 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
30050 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
30060 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
30070 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
30080 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
30090 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
300a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
300b0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
300c0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
300d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
300e0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
300f0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
30100 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
30110 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
30120 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
30130 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
30140 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
30150 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
30160 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
30170 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
30180 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
30190 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
301a0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
301b0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
301c0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
301d0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
301e0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
301f0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
30200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
30210 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
30220 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
30230 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30240 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
30250 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
30260 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
30270 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
30280 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
30290 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
302a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
302b0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
302c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
302d0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
302e0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
302f0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
30300 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
30310 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
30320 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
30330 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
30340 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
30350 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
30360 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
30370 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
30380 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
30390 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
303a0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
303b0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
303c0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
303d0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
303e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
303f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
30400 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
30410 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30420 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
30430 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
30440 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
30450 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
30460 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
30470 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
30480 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
30490 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
304a0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
304b0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
304c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
304d0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
304e0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
304f0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
30500 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
30510 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
30520 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
30530 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
30540 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
30550 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
30560 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
30570 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
30580 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
30590 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
305a0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
305b0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
305c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
305d0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
305e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
305f0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
30600 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
30610 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
30620 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
30630 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
30640 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
30650 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
30660 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
30670 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
30680 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
30690 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
306a0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
306b0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
306c0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
306d0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
306e0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
306f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30700 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
30710 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
30720 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
30730 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
30740 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
30750 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
30760 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
30770 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
30780 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
30790 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
307a0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
307b0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
307c0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
307d0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
307e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
307f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
30800 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
30810 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
30820 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
30830 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
30840 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
30850 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
30860 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
30870 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
30880 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30890 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
308a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
308b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
308c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
308d0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
308e0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
308f0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
30900 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
30910 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
30920 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
30930 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
30940 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
30950 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
30960 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
30970 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
30980 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
30990 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
309a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
309b0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
309c0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
309d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
309e0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
309f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
30a00 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
30a10 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
30a20 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
30a30 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
30a40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
30a50 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
30a60 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
30a70 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
30a80 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
30a90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30aa0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
30ab0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
30ac0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
30ad0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
30ae0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
30af0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
30b00 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30b10 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
30b20 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
30b30 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
30b40 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
30b50 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
30b60 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
30b70 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
30b80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
30b90 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
30ba0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
30bb0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
30bc0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
30bd0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
30be0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
30bf0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
30c00 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
30c10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
30c20 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
30c30 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
30c40 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
30c50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30c60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
30c70 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
30c80 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
30c90 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30ca0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
30cb0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
30cc0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
30cd0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
30ce0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
30cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30d00 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
30d10 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
30d20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
30d30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
30d40 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
30d50 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
30d60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
30d70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
30d80 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
30d90 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
30da0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30db0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
30dc0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
30dd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
30de0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
30df0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
30e00 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
30e10 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
30e20 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
30e30 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
30e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30e50 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
30e60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
30e70 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
30e80 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
30e90 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
30ea0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
30eb0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
30ec0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
30ed0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
30ee0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
30ef0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
30f00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30f10 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
30f20 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
30f30 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
30f40 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
30f50 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
30f60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
30f70 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
30f80 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
30f90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
30fa0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
30fb0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
30fc0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
30fd0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
30fe0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
30ff0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
31000 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
31010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31020 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
31030 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
31040 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
31050 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
31060 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
31070 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
31080 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
31090 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
310a0 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
310b0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
310c0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
310d0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
310e0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
310f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
31100 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
31110 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
31120 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
31130 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31140 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
31150 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31160 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
31170 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31180 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
31190 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
311a0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
311b0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
311c0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
311d0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
311e0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
311f0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
31200 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
31210 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
31220 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
31230 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
31240 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
31250 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31260 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
31270 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
31280 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
31290 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
312a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
312b0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
312c0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
312d0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
312e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
312f0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
31300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31310 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
31320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
31330 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31340 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
31350 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
31360 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
31370 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
31380 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
31390 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
313a0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
313b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
313c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
313d0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
313e0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
313f0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
31400 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
31410 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
31420 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
31430 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
31440 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
31450 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
31460 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
31470 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
31480 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
31490 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
314a0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
314b0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
314c0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
314d0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
314e0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
314f0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
31500 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31510 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
31520 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
31530 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
31540 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
31550 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
31560 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
31570 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
31580 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
31590 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
315a0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
315b0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
315c0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
315d0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
315e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
315f0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
31600 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
31610 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
31620 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
31630 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
31640 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
31650 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
31660 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
31670 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
31680 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
31690 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
316a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
316b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
316c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
316d0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
316e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
316f0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
31700 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
31710 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
31720 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
31730 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
31740 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
31750 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
31760 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
31770 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
31780 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
31790 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
317a0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
317b0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
317c0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
317d0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
317e0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
317f0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
31800 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
31810 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
31820 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
31830 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
31840 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
31850 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
31860 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
31870 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
31880 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
31890 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
318a0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
318b0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
318c0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
318d0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
318e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
318f0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
31900 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
31910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31920 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
31930 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
31940 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
31950 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
31960 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
31970 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
31980 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
31990 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
319a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
319b0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
319c0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
319d0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
319e0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
319f0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
31a00 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
31a10 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
31a20 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
31a30 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
31a40 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
31a50 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
31a60 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
31a70 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
31a80 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
31a90 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
31aa0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
31ab0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
31ac0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
31ad0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
31ae0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
31af0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
31b00 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
31b10 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
31b20 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
31b30 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
31b40 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
31b50 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
31b60 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
31b70 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
31b80 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
31b90 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
31ba0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
31bb0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
31bc0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
31bd0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
31be0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
31bf0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
31c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
31c10 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
31c20 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
31c30 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
31c40 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
31c50 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
31c60 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
31c70 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
31c80 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
31c90 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
31ca0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
31cb0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
31cc0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
31cd0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
31ce0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
31cf0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
31d00 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
31d10 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
31d20 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
31d30 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
31d40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
31d50 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
31d60 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
31d70 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
31d80 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
31d90 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
31da0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
31db0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
31dc0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
31dd0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
31de0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
31df0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
31e00 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
31e10 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
31e20 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
31e30 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
31e40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
31e50 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
31e60 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
31e70 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
31e80 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
31e90 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
31ea0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
31eb0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
31ec0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
31ed0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
31ee0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
31ef0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
31f00 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
31f10 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
31f20 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
31f30 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
31f40 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
31f50 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
31f60 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
31f70 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
31f80 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
31f90 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
31fa0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
31fb0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
31fc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
31fd0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
31fe0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
31ff0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
32000 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
32010 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
32020 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
32030 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
32040 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
32050 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
32060 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
32070 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
32080 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
32090 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
320a0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
320b0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
320c0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
320d0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
320e0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
320f0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
32100 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
32110 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
32120 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
32130 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32140 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
32150 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
32160 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
32170 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
32180 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
32190 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
321a0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
321b0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
321c0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
321d0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
321e0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
321f0 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
32200 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
32210 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
32220 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
32230 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
32240 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
32250 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
32260 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
32270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
32280 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
32290 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
322a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
322b0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
322c0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
322d0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
322e0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
322f0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
32300 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
32310 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
32320 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
32330 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
32340 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
32350 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
32360 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
32370 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
32380 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
32390 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
323a0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
323b0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
323c0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
323d0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
323e0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
323f0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
32400 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
32410 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
32420 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
32430 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
32440 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
32450 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
32460 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
32470 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
32480 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32490 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
324a0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
324b0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
324c0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
324d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
324e0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
324f0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
32500 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
32510 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
32520 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
32530 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
32540 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
32550 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
32560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
32570 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
32580 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
32590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
325a0 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
325b0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
325c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
325d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
325e0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
325f0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
32600 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
32610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
32620 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
32630 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32640 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
32650 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
32660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
32670 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32680 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
32690 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
326a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
326b0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
326c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
326d0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
326e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
326f0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
32700 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
32710 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
32720 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
32730 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
32740 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
32750 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
32760 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
32770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32780 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
32790 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
327a0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
327b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
327c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
327d0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
327e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
327f0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
32800 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
32810 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32820 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
32830 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
32840 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
32850 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
32860 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
32870 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
32880 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
32890 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
328a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
328b0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
328c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
328d0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
328e0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
328f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
32900 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
32910 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
32920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32930 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
32940 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
32950 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
32960 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
32970 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
32980 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
32990 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
329a0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
329b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
329c0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
329d0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
329e0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
329f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
32a00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
32a10 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
32a20 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
32a30 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
32a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32a50 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
32a60 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
32a70 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
32a80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
32a90 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
32aa0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
32ab0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
32ac0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
32ad0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
32ae0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
32af0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
32b00 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
32b10 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
32b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32b30 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
32b40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32b50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
32b60 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
32b70 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
32b80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32b90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
32ba0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
32bb0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
32bc0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
32bd0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
32be0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
32bf0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
32c00 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
32c10 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
32c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32c30 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
32c40 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
32c50 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
32c60 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
32c70 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
32c80 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
32c90 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
32ca0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
32cb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
32cc0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
32cd0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
32ce0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
32cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32d00 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
32d10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
32d20 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
32d30 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
32d40 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
32d50 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
32d60 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
32d70 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32d80 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
32d90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32da0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
32db0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
32dc0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
32dd0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
32de0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
32df0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
32e00 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
32e10 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
32e20 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
32e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e40 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
32e50 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
32e60 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
32e70 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
32e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32e90 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
32ea0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
32eb0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
32ec0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
32ed0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
32ee0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
32ef0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
32f00 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
32f10 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
32f20 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
32f30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
32f40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
32f50 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
32f60 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
32f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
32f80 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
32f90 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
32fa0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
32fb0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
32fc0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
32fd0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
32fe0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
32ff0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
33000 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
33010 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
33020 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
33030 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
33040 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
33050 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
33060 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
33070 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
33080 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
33090 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
330a0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
330b0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
330c0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
330d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
330e0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
330f0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
33100 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
33110 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
33120 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
33130 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
33140 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
33150 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
33160 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
33170 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
33180 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
33190 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
331a0 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
331b0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
331c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
331d0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
331e0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
331f0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
33200 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
33210 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
33220 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
33230 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
33240 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
33250 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
33260 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
33270 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
33280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33290 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
332a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
332b0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
332c0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
332d0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
332e0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
332f0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
33300 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
33310 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
33320 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
33330 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
33340 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
33350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33360 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
33370 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
33380 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
33390 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
333a0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
333b0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
333c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
333d0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
333e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
333f0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
33400 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33410 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
33420 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
33430 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
33440 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
33450 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
33460 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
33470 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
33480 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
33490 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
334a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
334b0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
334c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
334d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
334e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
334f0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
33500 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
33510 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
33520 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
33530 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
33540 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
33550 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
33560 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
33570 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
33580 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
33590 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
335a0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
335b0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
335c0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
335d0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
335e0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
335f0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
33600 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
33610 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
33620 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
33630 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
33640 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
33650 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
33660 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
33670 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
33680 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
33690 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
336a0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
336b0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
336c0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
336d0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
336e0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
336f0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
33700 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
33710 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
33720 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
33730 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
33740 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
33750 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
33760 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
33770 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
33780 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
33790 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
337a0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
337b0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
337c0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
337d0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
337e0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
337f0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
33800 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
33810 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
33820 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
33830 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
33840 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
33850 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
33860 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
33870 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
33880 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
33890 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
338a0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
338b0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
338c0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
338d0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
338e0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
338f0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
33900 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
33910 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
33920 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
33930 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
33940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33950 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
33960 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
33970 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
33980 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33990 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
339a0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
339b0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
339c0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
339d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
339e0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
339f0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
33a00 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
33a10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
33a20 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
33a30 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
33a40 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
33a50 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
33a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
33a70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
33a80 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
33a90 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
33aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
33ab0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
33ac0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
33ad0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
33ae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33af0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
33b00 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
33b10 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
33b20 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
33b30 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
33b40 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
33b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33b60 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
33b70 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
33b80 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
33b90 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
33ba0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
33bb0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
33bc0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
33bd0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
33be0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
33bf0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
33c00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33c10 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
33c20 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
33c30 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
33c40 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
33c50 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
33c60 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
33c70 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
33c80 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
33c90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
33ca0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
33cb0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
33cc0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
33cd0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
33ce0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
33cf0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
33d00 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
33d10 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
33d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33d30 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
33d40 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
33d50 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
33d60 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
33d70 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
33d80 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
33d90 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
33da0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
33db0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
33dc0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
33dd0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
33de0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
33df0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
33e00 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
33e10 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
33e20 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
33e30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
33e40 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
33e50 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
33e60 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
33e70 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
33e80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
33e90 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
33ea0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
33eb0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
33ec0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
33ed0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
33ee0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
33ef0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
33f00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
33f10 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
33f20 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
33f30 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
33f40 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
33f50 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
33f60 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
33f70 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
33f80 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
33f90 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
33fa0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
33fb0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
33fc0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
33fd0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
33fe0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
33ff0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
34000 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
34010 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
34020 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
34030 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
34040 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
34050 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
34060 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
34070 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
34080 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
34090 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
340a0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
340b0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
340c0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
340d0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
340e0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
340f0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
34100 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
34110 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
34120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34130 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
34140 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
34150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34160 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
34170 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
34180 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
34190 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
341a0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
341b0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
341c0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
341d0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
341e0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
341f0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
34200 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
34210 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
34220 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
34230 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
34240 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
34250 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
34260 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
34270 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
34280 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34290 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
342a0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
342b0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
342c0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
342d0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
342e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
342f0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
34300 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
34310 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
34320 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
34330 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
34340 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
34350 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
34360 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
34370 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
34380 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
34390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
343a0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
343b0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
343c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
343d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
343e0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
343f0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
34400 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
34410 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
34420 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
34430 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
34440 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
34450 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
34460 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
34470 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
34480 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
34490 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
344a0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
344b0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
344c0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
344d0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
344e0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
344f0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
34500 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
34510 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
34520 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
34530 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
34540 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
34550 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
34560 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
34570 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
34580 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
34590 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
345a0 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
345b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
345c0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
345d0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
345e0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
345f0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
34600 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
34610 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
34620 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
34630 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
34640 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
34650 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
34660 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
34670 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
34680 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
34690 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
346a0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
346b0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
346c0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
346d0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
346e0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
346f0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
34700 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
34710 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
34720 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
34730 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
34740 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
34750 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
34760 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
34770 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
34780 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
34790 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
347a0 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
347b0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
347c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
347d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
347e0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
347f0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
34800 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
34810 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
34820 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
34830 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
34840 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
34850 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
34860 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
34870 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
34880 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
34890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
348a0 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
348b0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
348c0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
348d0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
348e0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
348f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
34900 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
34910 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
34920 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34930 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
34940 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
34950 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
34960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
34970 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
34980 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
34990 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
349a0 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
349b0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
349c0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
349d0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
349e0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
349f0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
34a00 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
34a10 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
34a20 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
34a30 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
34a40 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
34a50 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
34a60 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
34a70 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
34a80 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
34a90 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
34aa0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
34ab0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
34ac0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
34ad0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
34ae0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
34af0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
34b00 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
34b10 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
34b20 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
34b30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34b40 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
34b50 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
34b60 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
34b70 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
34b80 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
34b90 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
34ba0 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
34bb0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
34bc0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
34bd0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
34be0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
34bf0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
34c00 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
34c10 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
34c20 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
34c30 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
34c40 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
34c50 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
34c60 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
34c70 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
34c80 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
34c90 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
34ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
34cb0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
34cc0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
34cd0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
34ce0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
34cf0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
34d00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
34d10 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c  f SQLite..*/.sql
34d20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
34d30 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
34d40 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
34d50 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
34d60 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
34d70 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
34d80 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
34d90 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
34da0 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
34db0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
34dc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
34dd0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
34de0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
34df0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
34e00 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
34e10 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
34e20 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
34e30 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
34e40 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
34e50 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
34e60 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34e70 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
34e80 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
34e90 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
34ea0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
34eb0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
34ec0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b  ap_limit(int N);
34ed0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
34ee0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
34ef0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
34f00 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
34f10 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
34f20 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
34f30 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
34f40 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
34f50 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
34f60 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
34f70 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
34f80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34f90 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
34fa0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
34fb0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
34fc0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34fd0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
34fe0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
34ff0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
35000 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
35010 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
35020 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
35030 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
35040 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
35050 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
35060 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
35070 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
35080 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
35090 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
350a0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
350b0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
350c0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
350d0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
350e0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
350f0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
35100 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
35110 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
35120 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
35130 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
35140 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
35150 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
35160 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
35170 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
35180 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
35190 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
351a0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
351b0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
351c0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
351d0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
351e0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
351f0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
35200 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
35210 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
35220 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
35230 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
35240 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
35250 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
35260 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
35270 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
35280 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
35290 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
352a0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
352b0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
352c0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
352d0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
352e0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
352f0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
35300 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
35310 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
35320 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
35330 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
35340 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
35350 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
35360 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
35370 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
35380 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
35390 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
353a0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
353b0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
353c0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
353d0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
353e0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
353f0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
35400 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
35410 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
35420 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
35430 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
35440 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
35450 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
35460 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
35470 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
35480 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
35490 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
354a0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
354b0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
354c0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
354d0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
354e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
354f0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
35500 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
35510 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
35520 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
35530 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
35540 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
35550 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
35560 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
35570 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
35580 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
35590 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
355a0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
355b0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
355c0 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
355d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
355e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
355f0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
35600 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
35610 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
35620 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
35630 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
35640 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
35650 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
35660 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
35670 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
35680 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
35690 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
356a0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
356b0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
356c0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
356d0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
356e0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
356f0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
35700 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
35710 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
35720 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
35730 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
35740 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
35750 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
35760 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
35770 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
35780 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
35790 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
357a0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
357b0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
357c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
357d0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
357e0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
357f0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
35800 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
35810 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
35820 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
35830 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
35840 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
35850 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
35860 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
35870 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
35880 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
35890 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
358a0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
358b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
358c0 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
358d0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
358e0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
358f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
35900 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
35910 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
35920 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
35930 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
35940 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
35950 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
35960 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
35970 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
35980 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
35990 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
359a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
359b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
359c0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
359d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
359e0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
359f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
35a00 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
35a10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35a20 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
35a30 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
35a40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
35a50 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
35a60 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
35a70 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
35a80 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
35a90 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
35aa0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
35ab0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
35ac0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
35ad0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
35ae0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
35af0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
35b00 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
35b10 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
35b20 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
35b30 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
35b40 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
35b50 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
35b60 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
35b70 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
35b80 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
35b90 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
35ba0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
35bb0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
35bc0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
35bd0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
35be0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
35bf0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
35c00 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
35c10 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
35c20 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
35c30 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
35c40 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
35c50 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
35c60 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
35c70 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
35c80 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
35c90 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
35ca0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
35cb0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
35cc0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
35cd0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
35ce0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
35cf0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
35d00 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
35d10 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
35d20 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
35d30 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
35d40 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
35d50 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
35d60 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
35d70 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
35d80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
35d90 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
35da0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
35db0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
35dc0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
35dd0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
35de0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
35df0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
35e00 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
35e10 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
35e20 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
35e30 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
35e40 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
35e50 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
35e60 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
35e70 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
35e80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
35e90 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
35ea0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
35eb0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
35ec0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
35ed0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
35ee0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
35ef0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
35f00 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
35f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
35f20 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
35f30 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
35f40 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
35f50 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
35f60 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
35f70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
35f80 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
35f90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
35fa0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
35fb0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
35fc0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
35fd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
35fe0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
35ff0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
36000 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
36010 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
36020 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
36030 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
36040 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
36050 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
36060 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
36070 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
36080 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
36090 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
360a0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
360b0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
360c0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
360d0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
360e0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
360f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
36100 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
36110 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
36120 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
36130 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
36140 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
36150 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
36160 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
36170 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
36180 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
36190 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
361a0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
361b0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
361c0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
361d0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
361e0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
361f0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
36200 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
36210 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
36220 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
36230 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
36240 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
36250 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
36260 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
36270 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
36280 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
36290 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
362a0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
362b0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
362c0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
362d0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
362e0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
362f0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
36300 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
36310 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
36320 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36330 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
36340 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
36350 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
36360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36370 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
36380 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
36390 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
363a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
363b0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
363c0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
363d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
363e0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
363f0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
36400 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
36410 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
36420 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
36430 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
36440 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
36450 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
36460 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
36470 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
36480 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
36490 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
364a0 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
364b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
364c0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
364d0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
364e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
364f0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
36500 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
36510 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
36520 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
36530 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
36540 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
36550 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
36560 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
36570 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
36580 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
36590 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
365a0 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
365b0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
365c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
365d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
365e0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
365f0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
36600 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
36610 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
36620 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
36630 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
36640 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
36650 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
36660 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
36670 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
36680 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
36690 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
366a0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
366b0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
366c0 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
366d0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
366e0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
366f0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
36700 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
36710 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36720 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
36730 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
36740 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
36750 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
36760 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
36770 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
36780 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
36790 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
367a0 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
367b0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
367c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
367d0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
367e0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
367f0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
36800 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
36810 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
36820 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
36830 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
36840 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
36850 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
36860 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
36870 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
36880 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
36890 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
368a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
368b0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
368c0 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
368d0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
368e0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
368f0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
36900 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
36910 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
36920 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
36930 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
36940 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
36950 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
36960 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
36970 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
36980 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
36990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
369a0 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
369b0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sion()]..*/.int 
369c0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
369d0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
369e0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
369f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36a00 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
36a10 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
36a20 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ading.**.** ^Thi
36a30 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61  s interface disa
36a40 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74  bles all automat
36a50 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72  ic extensions pr
36a60 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69  eviously.** regi
36a70 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
36a80 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
36a90 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  sion()]..*/.void
36aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
36ab0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
36ac0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
36ad0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
36ae0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
36af0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
36b00 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
36b10 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
36b20 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
36b30 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
36b40 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
36b50 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
36b60 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
36b70 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
36b80 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
36b90 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
36ba0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
36bb0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
36bc0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
36bd0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
36be0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
36bf0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
36c00 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
36c10 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
36c20 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
36c30 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
36c40 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
36c50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
36c60 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
36c70 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
36c80 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
36c90 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
36ca0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
36cb0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
36cc0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
36cd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
36ce0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
36cf0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
36d00 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
36d10 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
36d20 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
36d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36d40 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
36d50 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
36d60 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
36d70 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
36d80 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
36d90 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
36da0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
36db0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
36dc0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
36dd0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
36de0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
36df0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
36e00 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
36e10 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
36e20 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
36e30 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
36e40 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
36e50 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
36e60 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
36e70 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
36e80 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
36e90 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
36ea0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
36eb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
36ec0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
36ed0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36ee0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
36ef0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
36f00 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
36f10 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
36f20 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
36f30 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
36f40 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
36f50 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
36f60 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
36f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
36f80 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
36f90 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
36fa0 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
36fb0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
36fc0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
36fd0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
36fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
36ff0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
37000 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
37010 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
37020 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
37030 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
37040 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37050 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
37060 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
37070 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
37080 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
37090 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
370a0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
370b0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
370c0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
370d0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
370e0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
370f0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
37100 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
37110 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
37120 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
37130 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
37140 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37150 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
37160 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
37170 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
37180 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37190 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
371a0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
371b0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
371c0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
371d0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
371e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
371f0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
37200 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
37210 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
37220 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
37230 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
37240 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
37250 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
37260 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
37270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
37280 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
37290 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
372a0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
372b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
372c0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
372d0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
372e0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
372f0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
37300 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
37310 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
37320 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
37330 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
37340 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
37350 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
37360 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
37370 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
37380 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
37390 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
373a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
373b0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
373c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
373d0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
373e0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
373f0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
37400 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
37410 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37420 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
37430 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
37440 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
37450 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
37460 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
37470 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
37480 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
37490 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
374a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
374b0 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
374c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
374d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
374e0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
374f0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
37500 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
37510 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
37520 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
37530 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
37540 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68  );.  /* The meth
37550 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
37560 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
37570 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20  e sqlite_module 
37580 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20  object. Those . 
37590 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f   ** below are fo
375a0 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  r version 2 and 
375b0 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e  greater. */.  in
375c0 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28  t (*xSavepoint)(
375d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
375e0 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  Tab, int);.  int
375f0 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c   (*xRelease)(sql
37600 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
37610 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
37620 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c  xRollbackTo)(sql
37630 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
37640 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  , int);.};../*.*
37650 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
37660 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
37670 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
37680 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
37690 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
376a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
376b0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
376c0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
376d0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
376e0 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f  sed as part.** o
376f0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
37700 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20  able] interface 
37710 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
37720 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
37730 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
37740 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
37750 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
37760 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
37770 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
37780 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
37790 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
377a0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
377b0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
377c0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
377d0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
377e0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
377f0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
37800 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
37810 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
37820 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
37830 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
37840 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
37850 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
37860 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63  ** <blockquote>c
37870 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62  olumn OP expr</b
37880 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
37890 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
378a0 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
378b0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20  ;, or &gt;=.)^  
378c0 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  ^(The particular
378d0 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
378e0 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
378f0 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67  raint[].op using
37900 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   one of the.** [
37910 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
37920 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c  STRAINT_EQ | SQL
37930 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
37940 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e  AINT_ values].)^
37950 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20  .** ^(The index 
37960 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
37970 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
37980 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
37990 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
379a0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
379b0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
379c0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
379d0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
379e0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
379f0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
37a00 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
37a10 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
37a20 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
37a30 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
37a40 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
37a50 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
37a60 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
37a70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
37a80 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
37a90 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
37aa0 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
37ab0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
37ac0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
37ad0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
37ae0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
37af0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
37b00 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
37b10 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
37b20 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
37b30 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
37b40 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61  use terms that a
37b50 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74  re.** relevant t
37b60 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
37b70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
37b80 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
37b90 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e  .** ^Information
37ba0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
37bb0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
37bc0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
37bd0 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72  []..** ^Each ter
37be0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
37bf0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
37c00 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
37c10 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
37c20 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65   [xBestIndex] me
37c30 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
37c40 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
37c50 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
37c60 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
37c70 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
37c80 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
37c90 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30   ^If argvIndex>0
37ca0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
37cb0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
37cc0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
37cd0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
37ce0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
37cf0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
37d00 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
37d10 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49  ry in argv.  ^(I
37d20 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
37d30 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
37d40 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
37d50 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
37d60 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
37d70 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
37d80 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
37d90 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
37da0 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
37db0 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ite.)^.**.** ^Th
37dc0 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
37dd0 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
37de0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
37df0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
37e00 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
37e10 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72  .** ^[sqlite3_fr
37e20 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
37e30 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
37e40 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e  and only if.** n
37e50 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
37e60 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e  is true..**.** ^
37e70 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
37e80 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
37e90 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
37ea0 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
37eb0 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
37ec0 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
37ed0 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
37ee0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
37ef0 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
37f00 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
37f10 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
37f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d  **.** ^The estim
37f30 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
37f40 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
37f50 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
37f60 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
37f70 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
37f80 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
37f90 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
37fa0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
37fb0 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
37fc0 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
37fd0 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
37fe0 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
37ff0 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
38000 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
38010 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
38020 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
38030 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
38040 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
38050 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
38060 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
38070 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
38080 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
38090 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
380a0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
380b0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
380c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
380d0 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
380e0 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
380f0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
38100 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
38110 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
38120 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
38130 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
38140 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
38150 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
38160 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
38170 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
38180 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
38190 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
381a0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
381b0 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
381c0 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
381d0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
381e0 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
381f0 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
38200 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
38210 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
38220 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
38230 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
38240 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
38250 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
38260 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
38270 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
38280 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
38290 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
382a0 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
382b0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
382c0 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
382d0 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
382e0 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
382f0 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
38300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
38310 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
38320 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
38330 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
38340 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
38350 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
38360 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
38370 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
38380 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
38390 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
383a0 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
383b0 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
383c0 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
383d0 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
383e0 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
383f0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
38400 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
38410 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
38420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38430 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
38440 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
38450 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
38460 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
38470 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
38480 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
38490 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
384a0 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
384b0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
384c0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
384d0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
384e0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
384f0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
38500 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
38510 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
38520 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
38530 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
38540 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
38550 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
38560 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
38570 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
38580 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
38590 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
385a0 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65  e Constraint Ope
385b0 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a  rator Codes.**.*
385c0 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64  * These macros d
385d0 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77  efined the allow
385e0 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  ed values for th
385f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  e.** [sqlite3_in
38600 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74  dex_info].aConst
38610 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64  raint[].op field
38620 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65  .  Each value re
38630 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f  presents.** an o
38640 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20  perator that is 
38650 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72  part of a constr
38660 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65  aint term in the
38670 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66   wHERE clause of
38680 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74  .** a query that
38690 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c   uses a [virtual
386a0 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66   table]..*/.#def
386b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
386c0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
386d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
386e0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
386f0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
38700 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
38710 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
38720 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
38730 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
38740 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
38750 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
38760 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
38770 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
38780 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
38790 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
387a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
387b0 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
387c0 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
387d0 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  ntation.**.** ^T
387e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
387f0 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  e used to regist
38800 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  er a new [virtua
38810 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
38820 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65  name..** ^Module
38830 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must